├── .gitignore ├── .readthedocs.yaml ├── Makefile ├── README.md ├── _static ├── css │ └── 86box.css └── js │ └── 86box.js ├── conf.py ├── dev ├── api │ ├── device.rst │ ├── dma.rst │ ├── images │ │ ├── deviceconfig.png │ │ └── pciint.png │ ├── index.rst │ ├── io.rst │ ├── pci.rst │ ├── thread.rst │ └── timer.rst ├── buildguide.rst ├── builds.rst └── formats │ ├── 86f.rst │ ├── hdx.rst │ └── index.rst ├── graphics.pptx ├── guides └── .gitkeep ├── hardware ├── diskimages.rst ├── ideterqua.rst ├── images │ ├── ideterqua_win98.png │ └── isabugger.png ├── isabugger.rst ├── keyboard.rst ├── machinespecific.rst └── network.rst ├── icons.sh ├── include.rst ├── index.rst ├── make.bat ├── requirements.txt ├── settings ├── display.rst ├── floppycdrom.rst ├── hdd.rst ├── index.rst ├── input.rst ├── machine.rst ├── network.rst ├── peripherals.rst ├── ports.rst ├── removable.rst ├── sound.rst └── storage.rst └── usage ├── faq.rst ├── gettingstarted.rst ├── images ├── acpi_shutdown.png ├── acpi_shutdown_small.png ├── caps_lock_off.png ├── caps_lock_off_small.png ├── caps_lock_on.png ├── caps_lock_on_small.png ├── cartridge.png ├── cartridge_small.png ├── cassette.png ├── cassette_small.png ├── cdrom.png ├── cdrom_folder.png ├── cdrom_folder_small.png ├── cdrom_host.png ├── cdrom_host_small.png ├── cdrom_image.png ├── cdrom_image_small.png ├── cdrom_small.png ├── display.png ├── display_small.png ├── floppy_35.png ├── floppy_35_small.png ├── floppy_525.png ├── floppy_525_small.png ├── floppy_and_cdrom_drives.png ├── floppy_and_cdrom_drives_small.png ├── hard_disk.png ├── hard_disk_small.png ├── hard_reset.png ├── hard_reset_small.png ├── input_devices.png ├── input_devices_small.png ├── kana_lock_off.png ├── kana_lock_off_small.png ├── kana_lock_on.png ├── kana_lock_on_small.png ├── machine.png ├── machine_small.png ├── mo.png ├── mo_small.png ├── network.png ├── network_small.png ├── num_lock_off.png ├── num_lock_off_small.png ├── num_lock_on.png ├── num_lock_on_small.png ├── other_peripherals.png ├── other_peripherals_small.png ├── other_removable_devices.png ├── other_removable_devices_small.png ├── pause.png ├── pause_small.png ├── ports.png ├── ports_small.png ├── run.png ├── run_small.png ├── scroll_lock_off.png ├── scroll_lock_off_small.png ├── scroll_lock_on.png ├── scroll_lock_on_small.png ├── send_cad.png ├── send_cad_small.png ├── send_cae.png ├── send_cae_small.png ├── settings.png ├── settings_small.png ├── sound.png ├── sound_small.png ├── storage_controllers.png ├── storage_controllers_small.png ├── warning.png ├── warning_small.png ├── zip.png └── zip_small.png ├── menubar.rst ├── roms.rst ├── statusbar.rst └── toolbar.rst /.gitignore: -------------------------------------------------------------------------------- 1 | _build/ -------------------------------------------------------------------------------- /.readthedocs.yaml: -------------------------------------------------------------------------------- 1 | version: 2 2 | 3 | build: 4 | os: "ubuntu-24.04" 5 | tools: 6 | python: "3.13" 7 | 8 | python: 9 | install: 10 | - requirements: requirements.txt 11 | 12 | sphinx: 13 | configuration: conf.py 14 | 15 | formats: all 16 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | # Minimal makefile for Sphinx documentation 2 | # 3 | 4 | # You can set these variables from the command line, and also 5 | # from the environment for the first two. 6 | SPHINXOPTS ?= 7 | SPHINXBUILD ?= sphinx-build 8 | SOURCEDIR = . 9 | BUILDDIR = _build 10 | 11 | # Put it first so that "make" without argument is like "make help". 12 | help: 13 | @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 14 | 15 | .PHONY: help Makefile 16 | 17 | # Catch-all target: route all unknown targets to Sphinx using the new 18 | # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). 19 | %: Makefile 20 | @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 21 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | Documentation for 86Box 2 | ======================= 3 | [![Documentation Status](https://readthedocs.org/projects/86box/badge/?version=latest)](https://86box.readthedocs.io/en/latest/?badge=latest) 4 | -------------------------------------------------------------------------------- /_static/css/86box.css: -------------------------------------------------------------------------------- 1 | /* Give some spacing to icons in headings. */ 2 | h1 > img, 3 | h2 > img { 4 | padding-right: 5px; 5 | } 6 | 7 | /* Remove bottom spacing from lists in tables and admonitions. */ 8 | table.docutils ul, table.docutils ol { 9 | margin-bottom: 0 !important; 10 | } 11 | div.admonition > p:nth-child(2) { 12 | margin-bottom: 0; 13 | } 14 | 15 | /* Avoid horizontal scrolling of API documentation tables. */ 16 | .wy-table-responsive table td { 17 | white-space: normal; 18 | } 19 | 20 | /* Tweak API documentation table titles. */ 21 | .rst-content table.docutils caption, 22 | .rst-content table.docutils caption span { 23 | padding-top: 0; 24 | font-style: normal; 25 | } 26 | .rst-content table.docutils caption code { 27 | font-size: inherit; 28 | font-style: normal; 29 | border: none; 30 | background: none; 31 | padding: 0; 32 | } 33 | 34 | /* Fix font size for some elements in table cells. */ 35 | .rst-content table.docutils li > p, 36 | .rst-content table.docutils li > p { 37 | font-size: inherit; 38 | } 39 | .rst-content :not(.bit-table) > .wy-table-responsive > table.docutils td:not(:last-child) > p:only-child > code:only-child, 40 | .rst-content :not(.bit-table) > .wy-table-responsive > table.docutils tr > td:only-child > p:only-child > code:only-child { 41 | font-size: inherit; 42 | 43 | /* Additional tweaks for literal values alone in table cells. */ 44 | border: none; 45 | background: none; 46 | padding: 0; 47 | } 48 | 49 | /* Tweaks for nested tables. */ 50 | .rst-content table.docutils td .wy-table-responsive { 51 | margin-top: 0.5em; 52 | margin-bottom: 0; 53 | } 54 | .rst-content tr.row-odd > td { 55 | background-color: #fcfcfc !important; /* originally transparent */ 56 | } 57 | 58 | /* Text transformation for tables. */ 59 | div.vertical-text { 60 | transform: rotate(270deg); 61 | } 62 | 63 | /* Bitfield table. */ 64 | .rst-content .bit-table table th:not(.stub), 65 | .rst-content .bit-table table td { 66 | text-align: center; 67 | vertical-align: middle; 68 | min-width: 26px; /* two numeric digits */ 69 | padding: 0; /* only eliminates side padding, but good enough */ 70 | } 71 | .rst-content .bit-table table th code:only-child { 72 | font-size: inherit; 73 | font-weight: normal; 74 | border: none; 75 | background: none; 76 | padding: 0; 77 | } 78 | 79 | /* Toggle containers. toggle-always-show is a class that takes 80 | on the look of a toggle container, but is always shown. */ 81 | .rst-content .toggle, 82 | .rst-content .toggle-always-show { 83 | background: #f3f6f6; 84 | border: 1px solid #e1e4e5; 85 | padding: 1em; 86 | margin: 0 0 24px; 87 | } 88 | .rst-content .toggle-closed > .toggle-header, 89 | .rst-content .toggle-open > .toggle-header { 90 | cursor: pointer; 91 | } 92 | @media screen { /* show toggle arrows and hide toggle contents on screen only */ 93 | .rst-content .toggle-closed > .toggle-header > p:before { 94 | content: "\0025B6 "; 95 | } 96 | .rst-content .toggle-open > .toggle-header > p:before { 97 | content: "\0025BC "; 98 | } 99 | .rst-content .toggle-closed > div:nth-child(2) { 100 | display: none; 101 | } 102 | } 103 | .rst-content .toggle-header > p { 104 | font-weight: bold; 105 | margin-bottom: 0; 106 | } 107 | .rst-content .toggle > div:nth-child(2), 108 | .rst-content .toggle-always-show > div:nth-child(2) { 109 | margin-top: 12px; 110 | margin-bottom: 0; 111 | } 112 | 113 | /* Print stuff. */ 114 | @media print { 115 | /* Allow page breaks in the middle of code. */ 116 | pre { 117 | break-inside: auto; 118 | } 119 | 120 | /* Fix theme bug where code blocks have blank space at the end. */ 121 | .rst-content div[class^=highlight] { 122 | white-space: nowrap; 123 | } 124 | .rst-content div[class*="highlight-"] { 125 | white-space: pre-wrap; 126 | } 127 | 128 | /* Always show toggle containers. */ 129 | .rst-content .toggle-closed > div:nth-child(2) { 130 | display: block !important; 131 | } 132 | } 133 | -------------------------------------------------------------------------------- /_static/js/86box.js: -------------------------------------------------------------------------------- 1 | /* Toggle containers, modified from: https://stackoverflow.com/questions/2454577/sphinx-restructuredtext-show-hide-code-snippets */ 2 | $(document).ready(function() { 3 | /* Hide all toggle containers. */ 4 | $('.toggle').toggleClass('toggle-closed'); 5 | 6 | /* Add click handlers for the header. */ 7 | $('.toggle > .toggle-header').click(function() { 8 | /* Toggle the container. */ 9 | $(this).parent().children().not('.toggle-header').toggle(400); 10 | $(this).parent().toggleClass('toggle-open toggle-closed'); 11 | }); 12 | 13 | /* Fix scroll position if a heading is provided in the URL. 14 | Actually hit or miss but I can't think of a better solution. */ 15 | if ($('.toggle').length && document.location.hash) { 16 | $(window).on('load', function() { 17 | setTimeout(function() { 18 | var hash = document.location.hash; 19 | document.location.hash = hash + '_'; 20 | document.location.hash = hash; 21 | }, 0); 22 | }); 23 | } 24 | }); 25 | -------------------------------------------------------------------------------- /conf.py: -------------------------------------------------------------------------------- 1 | # Configuration file for the Sphinx documentation builder. 2 | # 3 | # This file only contains a selection of the most common options. For a full 4 | # list see the documentation: 5 | # https://www.sphinx-doc.org/en/master/usage/configuration.html 6 | import sphinx_rtd_theme, time 7 | 8 | # -- Path setup -------------------------------------------------------------- 9 | 10 | # If extensions (or modules to document with autodoc) are in another directory, 11 | # add these directories to sys.path here. If the directory is relative to the 12 | # documentation root, use os.path.abspath to make it absolute, like shown here. 13 | # 14 | # import os 15 | # import sys 16 | # sys.path.insert(0, os.path.abspath('.')) 17 | 18 | 19 | # -- Project information ----------------------------------------------------- 20 | 21 | project = '86Box' 22 | copyright = f'2020-{time.strftime("%Y")}, 86Box Project' 23 | author = '86Box Project' 24 | 25 | 26 | # -- General configuration --------------------------------------------------- 27 | 28 | # Add any Sphinx extension module names here, as strings. They can be 29 | # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom 30 | # ones. 31 | extensions = [ 32 | 'sphinx_rtd_theme', 33 | 'sphinx.ext.autosectionlabel', 34 | 'linuxdoc.rstFlatTable' 35 | ] 36 | autosectionlabel_prefix_document = True 37 | master_doc = 'index' 38 | 39 | # Add any paths that contain templates here, relative to this directory. 40 | templates_path = ['_templates'] 41 | 42 | # List of patterns, relative to source directory, that match files and 43 | # directories to ignore when looking for source files. 44 | # This pattern also affects html_static_path and html_extra_path. 45 | exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] 46 | 47 | 48 | # -- Options for HTML output ------------------------------------------------- 49 | 50 | # The theme to use for HTML and HTML Help pages. See the documentation for 51 | # a list of builtin themes. 52 | # 53 | html_theme = 'sphinx_rtd_theme' 54 | 55 | # Add any paths that contain custom static files (such as style sheets) here, 56 | # relative to this directory. They are copied after the builtin static files, 57 | # so a file named "default.css" will overwrite the builtin "default.css". 58 | html_static_path = ['_static'] 59 | 60 | html_css_files = [ 61 | 'css/86box.css', 62 | ] 63 | 64 | html_js_files = [ 65 | 'js/86box.js', 66 | ] 67 | 68 | highlight_language = 'c' 69 | -------------------------------------------------------------------------------- /dev/api/device.rst: -------------------------------------------------------------------------------- 1 | Devices 2 | ======= 3 | 4 | The **device** is the main unit of emulated components in 86Box. Each device is represented by one or more constant ``device_t`` objects, which contain metadata about the device itself, several callbacks and an array of user-facing configuration options. Unless otherwise stated, all structures, functions and constants in this page are provided by ``86box/device.h``. 5 | 6 | .. flat-table:: ``device_t`` 7 | :header-rows: 1 8 | :widths: 1 1 999 9 | 10 | * - :cspan:`1` Member 11 | - Description 12 | 13 | * - :cspan:`1` ``name`` 14 | - The device's name, displayed in the user interface. ``"Foo-1234"`` for example. Suffixes like ``"(PCI)"`` are removed at run-time. 15 | 16 | * - :cspan:`1` ``internal_name`` 17 | - The device's internal name, used to identify it in the emulated machine's configuration file. ``"foo1234"`` for example. 18 | 19 | * - :cspan:`1` ``flags`` 20 | - One or more bit flags to indicate the expansion bus(es) supported by the device, for determining :ref:`device availability ` on the selected machine: 21 | 22 | * ``DEVICE_ISA``: 8-bit ISA; 23 | * ``DEVICE_AT``: 16-bit ISA; 24 | * ``DEVICE_EISA``: EISA (reserved for future use); 25 | * ``DEVICE_VLB``: VESA Local Bus or proprietary equivalents; 26 | * ``DEVICE_PCI``: 32-bit PCI; 27 | * ``DEVICE_AGP``: AGP 3.3V; 28 | * ``DEVICE_AC97``: AMR, CNR or ACR; 29 | * ``DEVICE_PCJR``: IBM PCjr; 30 | * ``DEVICE_PS2``: IBM PS/1 or PS/2; 31 | * ``DEVICE_MCA``: IBM Micro Channel Architecture; 32 | * ``DEVICE_CBUS``: PC-98 C-BUS (reserved for future use); 33 | * ``DEVICE_COM``: serial port (reserved for future use); 34 | * ``DEVICE_LPT``: parallel port (reserved for future use). 35 | 36 | * - :cspan:`1` ``local`` 37 | - 32-bit value which can be read from this structure by the ``init`` callback. 38 | Use this value to tell different subtypes of the same device, for example. 39 | 40 | * - :cspan:`1` ``init`` 41 | - Function called whenever this device is initialized, either from starting 86Box or from a hard reset. Can be ``NULL``, in which case the opaque pointer passed to other callbacks will be invalid. Takes the form of: 42 | 43 | ``void *init(const struct device_t *info)`` 44 | 45 | * ``info``: pointer to this ``device_t`` structure; 46 | * Return value: opaque pointer passed to the other callbacks below, usually a pointer to the device's :ref:`state structure `. 47 | 48 | * - :cspan:`1` ``close`` 49 | - Function called whenever this device is de-initialized, either from closing 86Box or from a hard reset. Can be ``NULL``. Takes the form of: 50 | 51 | ``void close(void *priv)`` 52 | 53 | * ``priv``: opaque pointer previously returned by ``init``. 54 | 55 | * - :cspan:`1` ``reset`` 56 | - Function called whenever this device undergoes a soft reset. Can be ``NULL``. Takes the form of: 57 | 58 | ``void reset(void *priv)`` 59 | 60 | * ``priv``: opaque pointer previously returned by ``init``. 61 | 62 | * - :rspan:`2` 63 | 64 | .. raw:: html 65 | 66 |
union
67 | - ``available`` 68 | - Function called whenever this device's availability is being checked. Can be ``NULL``, in which case the device will always be available. Takes the form of: 69 | 70 | ``int available()`` 71 | 72 | * Return value: ``1`` if the device is available for selection, or ``0`` if it is unavailable (due to missing ROMs, for example). 73 | 74 | * - ``poll`` 75 | - Function called whenever the mouse position is updated. Valid for mouse devices only. Takes the form of: 76 | 77 | ``int poll(int x, int y, int z, int b, void *priv)`` 78 | 79 | * ``x`` and ``y``: relative mouse movement coordinates (signed); 80 | * ``z``: relative scroll wheel movement coordinate (signed); 81 | * ``b``: button state: bit 0 (``0x1``) set if left button pressed, bit 1 (``0x2``) set if right button pressed, bit 2 (``0x4``) set if middle button pressed; 82 | * ``priv``: opaque pointer previously returned by ``init``; 83 | * Return value: ``0`` if the change was processed, or any other value otherwise. 84 | 85 | * - ``register_pci_slot`` 86 | - Reserved for future use. 87 | 88 | * - :cspan:`1` ``speed_changed`` 89 | - Function called whenever the emulated CPU clock speed is changed. Can be ``NULL``. Timer intervals (when using the undocumented legacy timer API) and anything else sensitive to the CPU clock speed should be updated in this callback. Takes the form of: 90 | 91 | ``void speed_changed(void *priv)`` 92 | 93 | * ``priv``: opaque pointer previously returned by ``init``. 94 | 95 | * - :cspan:`1` ``force_redraw`` 96 | - Function called whenever the emulated screen has to be fully redrawn. Can be ``NULL``. Only useful for video cards. Takes the form of: 97 | 98 | ``void force_redraw(void *priv)`` 99 | 100 | * ``priv``: opaque pointer previously returned by ``init``. 101 | 102 | * - :cspan:`1` ``config`` 103 | - Array of :ref:`device configuration options `, or ``NULL`` if no options are available. 104 | 105 | State structure 106 | --------------- 107 | 108 | Most devices need a place to store their internal state. We discourage the use of global structures, and instead recommend allocating a **state structure** dynamically in the ``init`` callback and freeing it in the ``close`` callback. 109 | 110 | .. container:: toggle 111 | 112 | .. container:: toggle-header 113 | 114 | Code example: allocating and deallocating a state structure 115 | 116 | .. code-block:: 117 | 118 | #include <86box/device.h> 119 | 120 | typedef struct { 121 | uint32_t type; /* example: copied from device_t.local */ 122 | uint8_t regs[256]; /* example: 256*8-bit registers */ 123 | } foo_t; 124 | 125 | static void * 126 | foo_init(const device_t *info) 127 | { 128 | /* Allocate the device state structure. */ 129 | foo_t *dev = (foo_t *) malloc(sizeof(foo_t)); 130 | memset(dev, 0, sizeof(foo_t)); /* blank structure */ 131 | 132 | /* Do whatever you want. */ 133 | dev->type = info->local; /* copy device_t.local value */ 134 | 135 | /* Return a pointer to the state structure. */ 136 | return dev; 137 | } 138 | 139 | static void 140 | foo_close(void *priv) 141 | { 142 | /* Get the device state structure. */ 143 | foo_t *dev = (foo_t *) priv; 144 | 145 | /* Do whatever you want, then deallocate the state structure. */ 146 | free(dev); 147 | } 148 | 149 | const device_t foo1234_device = { 150 | .name = "Foo-1234", 151 | .internal_name = "foo1234", 152 | .flags = DEVICE_AT, /* 16-bit ISA */ 153 | .local = 1234, 154 | .init = foo_init, 155 | .close = foo_close, 156 | /* ... */ 157 | }; 158 | 159 | const device_t foo4321_device = { 160 | .name = "Foo-4321", 161 | .internal_name = "foo4321", 162 | .flags = DEVICE_PCI, /* 32-bit PCI */ 163 | .local = 4321, /* different device subtype */ 164 | .init = foo_init, 165 | .close = foo_close, 166 | /* ... */ 167 | }; 168 | 169 | Registration 170 | ------------ 171 | 172 | New devices must be **registered** before they can be selected by the user. This is usually accomplished by adding one or more ``device_t`` pointers to the **device table** for the device's class: 173 | 174 | * **Video cards:** ``video_cards`` in ``src/video/vid_table.c`` 175 | * **Sound cards:** ``sound_cards`` in ``src/sound/sound.c`` 176 | * **Network cards:** ``net_cards`` in ``src/network/network.c`` 177 | * **Parallel port devices:** ``lpt_devices`` in ``src/lpt.c`` 178 | * **Hard disk controllers:** ``controllers`` in ``src/disk/hdc.c`` 179 | * **Floppy disk controllers:** ``fdc_cards`` in ``src/floppy/fdc.c`` 180 | * **SCSI controllers:** ``scsi_cards`` in ``src/scsi/scsi.c`` 181 | * **ISA RTC cards:** ``boards`` in ``src/device/isartc.c`` 182 | * **ISA memory expansion cards:** ``boards`` in ``src/device/isamem.c`` 183 | 184 | Devices not covered by any of the above classes may require further integration through modifications to the user interface and configuration loading/saving systems. 185 | 186 | Availability 187 | ------------ 188 | 189 | A device will be **available** for selection by the user if these criteria are met: 190 | 191 | 1. The device is :ref:`registered `, so that the user interface knows about it; 192 | 2. The selected machine has any of the expansion buses specified in the device's ``flags``; 193 | 3. The device's ``available`` callback returns ``1`` to indicate the device is available (this will always be true if the ``available`` callback function is ``NULL``). 194 | 195 | The ``available`` callback can be used to verify the presence of ROM files if any ROMs are required by the device. 196 | 197 | .. container:: toggle 198 | 199 | .. container:: toggle-header 200 | 201 | Code example: ``available`` checking for the presence of a ROM 202 | 203 | .. code-block:: 204 | 205 | #include <86box/device.h> 206 | #include <86box/rom.h> 207 | 208 | static int 209 | foo1234_available() 210 | { 211 | return rom_present("roms/scsi/foo/foo1234.bin"); 212 | } 213 | 214 | const device_t foo1234_device = { 215 | /* ... */ 216 | { .available = foo1234_available }, /* must have brackets due to the union */ 217 | /* ... */ 218 | }; 219 | 220 | Configuration 221 | ------------- 222 | 223 | Devices can have any number of user-facing configuration options, usually accessed through the **Configure** button next to the selection box for the device's class: 224 | 225 | .. figure:: images/deviceconfig.png 226 | :align: center 227 | 228 | All option types currently configurable through the user interface. 229 | 230 | These options are stored in the emulated machine's configuration file, in a section identified by the device's ``name``: 231 | 232 | .. code-block:: none 233 | 234 | [Foo-1234] 235 | selection = 0 236 | hex16 = 0220 237 | hex20 = D8000 238 | fname = D:/VMs/86Box/86Box.exe 239 | binary = 1 240 | spinner = 1234 241 | midi_out = 0 242 | midi_in = 0 243 | 244 | 245 | Configuration options can be specified in the ``config`` member of ``device_t``, as a pointer to a ``const`` array of ``device_config_t`` objects terminated by an object of ``type`` ``CONFIG_END``. 246 | 247 | .. container:: toggle 248 | 249 | .. container:: toggle-header 250 | 251 | Code example: device configuration options 252 | 253 | .. code-block:: 254 | 255 | #include <86box/device.h> 256 | 257 | static const device_config_t foo_config[] = { 258 | { "selection", "Selection", CONFIG_SELECTION, "", 5, "", { 0 }, 259 | { 260 | { "IRQ 5", 5 }, 261 | { "IRQ 7", 7 }, 262 | { "" } 263 | } 264 | }, 265 | { "hex16", "16-bit hex", CONFIG_HEX16, "", 0x220, "", { 0 }, 266 | { 267 | { "0x220", 0x220 }, 268 | { "0x330", 0x330 }, 269 | { "" } 270 | } 271 | }, 272 | { "hex20", "20-bit hex", CONFIG_HEX20, "", 0xd8000, "", { 0 }, 273 | { 274 | /* While the memory *segment* is displayed to the user, we store the 275 | *linear* (segment << 4) base address in the configuration file. */ 276 | { "D800h", 0xd8000 }, 277 | { "DC00h", 0xdc000 }, 278 | { "" } 279 | } 280 | }, 281 | { "string", "String", CONFIG_STRING, "Default" }, 282 | { "fname", "Filename", CONFIG_FNAME, "", 0, "File type (*.foo)|*.foo|Another file type (*.bar)|*.bar" }, 283 | { "binary", "Binary", CONFIG_BINARY, "", 1 /* checked by default */ }, 284 | { "int", "Integer", CONFIG_INT, "", 1234 }, 285 | { "spinner", "Spinner", CONFIG_SPINNER, "", 1234, "", { 1204, 1294, 10 } }, 286 | { "mac", "MAC address", CONFIG_MAC, "", 0 }, 287 | { "midi_out", "MIDI output", CONFIG_MIDI_OUT, "", 0 }, 288 | { "midi_in", "MIDI input", CONFIG_MIDI_IN, "", 0 }, 289 | { "", "", CONFIG_END } 290 | }; 291 | 292 | const device_t foo_device = { 293 | /* ... */ 294 | .config = foo_config 295 | }; 296 | 297 | .. flat-table:: ``device_config_t`` 298 | :header-rows: 1 299 | :widths: 1 999 300 | 301 | * - Member 302 | - Description 303 | 304 | * - ``name`` 305 | - Internal name for this option, used to identify it in the emulated machine's configuration file. 306 | 307 | * - ``description`` 308 | - Description for this option, displayed in the user interface. 309 | 310 | * - ``type`` 311 | - One of the following option types: 312 | 313 | * ``CONFIG_SELECTION``: combobox containing a list of values specified by the ``selection`` member; 314 | * ``CONFIG_HEX16``: combobox containing a list of 16-bit hexadecimal values (useful for ISA I/O ports) specified by the ``selection`` member; 315 | * ``CONFIG_HEX20``: combobox containing a list of 20-bit hexadecimal values (useful for ISA memory addresses) specified by the ``selection`` member; 316 | * ``CONFIG_STRING``: arbitrary text string entered by the user, currently **not visible nor configurable** in the user interface; 317 | * ``CONFIG_FNAME``: arbitrary file path entered by the user directly or through a file selector button; 318 | * ``CONFIG_BINARY``: checkbox; 319 | * ``CONFIG_INT``: arbitrary integer number, currently **not visible nor configurable** in the user interface; 320 | * ``CONFIG_SPINNER``: arbitrary integer number entered by the user directly or through up/down arrows, within a range specified by the ``spinner`` member; 321 | * ``CONFIG_MAC``: last 3 octets of a MAC address, currently **not visible nor configurable** in the user interface; 322 | * ``CONFIG_MIDI_OUT``: combobox containing a list of system MIDI output devices; 323 | * ``CONFIG_MIDI_IN``: combobox containing a list of system MIDI input devices; 324 | * ``CONFIG_END``: **mandatory** terminator to indicate the end of the option list. 325 | 326 | * - ``default_string`` 327 | - Default string value for a ``CONFIG_STRING`` option. Can be ``""`` if not applicable. 328 | 329 | * - ``default_int`` 330 | - Default integer value for a ``CONFIG_HEX16``, ``CONFIG_HEX20``, ``CONFIG_BINARY``, ``CONFIG_INT`` or ``CONFIG_SPINNER`` option. Can be ``0`` if not applicable. 331 | 332 | * - ``file_filter`` 333 | - File type filter for a ``CONFIG_FNAME`` option. Can be ``""`` if not applicable. Must be specified in Windows ``description|mask|description|mask...`` format, for example: 334 | 335 | ``"Raw image (*.img)|*.img|Virtual Hard Disk (*.vhd)|*.vhd"`` 336 | 337 | * - ``spinner`` 338 | - ``device_config_spinner_t`` sub-structure containing the minimum/maximum/step values for a ``CONFIG_SPINNER`` option. Can be ``{ 0 }`` if not applicable. 339 | 340 | .. flat-table:: 341 | :header-rows: 1 342 | :widths: 1 999 343 | 344 | * - Member 345 | - Description 346 | 347 | * - ``min`` 348 | - Minimum selectable value. 349 | 350 | * - ``max`` 351 | - Maximum selectable value. 352 | 353 | * - ``step`` 354 | - Units to be incremented/decremented with the arrow buttons. Note that the user can still type in arbitrary numbers that are within ``min`` and ``max`` but not aligned to ``step``. 355 | 356 | * - ``selection`` 357 | - Array of ``device_config_selection_t`` sub-structures containing the choices for a ``CONFIG_SELECTION``, ``CONFIG_HEX16`` or ``CONFIG_HEX20`` option. Can be ``{ 0 }`` if not applicable. Must be terminated with an object with a ``description`` of ``""``. 358 | 359 | .. flat-table:: 360 | :header-rows: 1 361 | :widths: 1 999 362 | 363 | * - Member 364 | - Description 365 | 366 | * - ``description`` 367 | - Description for this choice, displayed in the user interface. 368 | 369 | * - ``value`` 370 | - Integer value corresponding to this choice, used to identify it in the emulated machine's configuration file. 371 | 372 | Configured option values can be read from within the device's ``init`` callback with the ``device_get_config_*`` functions. These functions automatically operate in the context of the device currently being initialized. 373 | 374 | .. note:: ``device_get_config_*`` functions should **never** be called outside of a device's ``init`` callback. You are responsible for reading the options' configured values in the ``init`` callback and storing them in the device's :ref:`state structure ` if necessary. 375 | 376 | .. flat-table:: ``device_get_config_string`` 377 | :header-rows: 1 378 | :widths: 1 999 379 | 380 | * - Parameter 381 | - Description 382 | 383 | * - ``name`` 384 | - The option's ``name``. Accepted option types are ``CONFIG_STRING`` and ``CONFIG_FNAME``. 385 | 386 | * - **Return value** 387 | - The option's configured string value, or its ``default_string`` if no value is present. Note that a ``const char *`` is returned. 388 | 389 | .. flat-table:: ``device_get_config_int`` / ``device_get_config_hex16`` / ``device_get_config_hex20`` 390 | :header-rows: 1 391 | :widths: 1 999 392 | 393 | * - Parameter 394 | - Description 395 | 396 | * - ``name`` 397 | - The option's ``name``. Accepted option types are: 398 | 399 | * ``device_get_config_int``: ``CONFIG_SELECTION``, ``CONFIG_BINARY``, ``CONFIG_INT``, ``CONFIG_SPINNER``, ``CONFIG_MIDI_OUT``, ``CONFIG_MIDI_IN`` 400 | * ``device_get_config_hex16``: ``CONFIG_HEX16`` 401 | * ``device_get_config_hex20``: ``CONFIG_HEX20`` 402 | 403 | * - **Return value** 404 | - The option's configured integer value (``CONFIG_BINARY`` returns 1 if checked or 0 otherwise), or its ``default_int`` if no value is present. 405 | 406 | .. flat-table:: ``device_get_config_int_ex`` / ``device_get_config_mac`` 407 | :header-rows: 1 408 | :widths: 1 999 409 | 410 | * - Parameter 411 | - Description 412 | 413 | * - ``name`` 414 | - The option's ``name``. Accepted option types are: 415 | 416 | * ``device_get_config_int_ex``: ``CONFIG_SELECTION``, ``CONFIG_BINARY``, ``CONFIG_INT``, ``CONFIG_SPINNER``, ``CONFIG_MIDI_OUT``, ``CONFIG_MIDI_IN`` 417 | * ``device_get_config_mac``: ``CONFIG_MAC`` 418 | 419 | * - ``dflt_int`` 420 | - The default value to return if no configured value is present. 421 | 422 | * - **Return value** 423 | - The option's configured integer value (``CONFIG_BINARY`` returns 1 if checked or 0 otherwise), or ``dflt_int`` if no value is present. 424 | -------------------------------------------------------------------------------- /dev/api/dma.rst: -------------------------------------------------------------------------------- 1 | DMA 2 | === 3 | 4 | 86Box offers two mechanisms for **Direct Memory Access**: 8237 DMA for ISA devices and direct memory read/write for PCI devices. 5 | 6 | 8237 DMA 7 | -------- 8 | 9 | ``86box/dma.h`` provides the ``dma_channel_read`` and ``dma_channel_write`` functions to read or write (respectively) a value from or to an **8237 DMA channel**. 10 | 11 | .. flat-table:: ``dma_channel_read`` 12 | :header-rows: 1 13 | :widths: 1 999 14 | 15 | * - Parameter 16 | - Description 17 | 18 | * - ``channel`` 19 | - DMA channel number: ``0``-``3`` for 8-bit channels or ``5``-``7`` for 16-bit channels. 20 | 21 | * - **Return value** 22 | - 8- (channels ``0``-``3``) or 16-bit (channels ``5``-``7``) value read from the given DMA channel, or ``DMA_NODATA`` if no data was read. 23 | 24 | May include a ``DMA_OVER`` bit flag (located above the most significant data bit so as to not interfere with the data) indicating that this was the last byte or word transferred, after which the channel is auto-initialized or masked depending on its configuration. 25 | 26 | .. flat-table:: ``dma_channel_write`` 27 | :header-rows: 1 28 | :widths: 1 999 29 | 30 | * - Parameter 31 | - Description 32 | 33 | * - ``channel`` 34 | - DMA channel number: ``0``-``3`` for 8-bit channels or ``5``-``7`` for 16-bit channels. 35 | 36 | * - ``val`` 37 | - 8- (channels ``0``-``3``) or 16-bit (channels ``5``-``7``) value to write to the given DMA channel. 38 | 39 | * - **Return value** 40 | - * ``0`` on success; 41 | * ``DMA_NODATA`` if no data was actually written; 42 | * ``DMA_OVER`` if this was the last byte or word transferred, after which the channel is auto-initialized or masked depending on its configuration. 43 | 44 | Direct memory read/write 45 | ------------------------ 46 | 47 | ``86box/mem.h`` provides the ``mem_read*_phys`` and ``mem_write*_phys`` functions, which read or write physical memory directly. These are useful for **PCI devices**, which perform DMA on their own. 48 | 49 | .. flat-table:: ``mem_readb_phys`` / ``mem_readw_phys`` / ``mem_readl_phys`` 50 | :header-rows: 1 51 | :widths: 1 999 52 | 53 | * - Parameter 54 | - Description 55 | 56 | * - ``addr`` 57 | - 32-bit memory address to read. 58 | 59 | * - **Return value** 60 | - 8- (``mem_readb_phys``), 16- (``mem_readw_phys``) or 32-bit (``mem_readl_phys``) value read from the given memory address. 61 | 62 | 63 | .. flat-table:: ``mem_writeb_phys`` / ``mem_writew_phys`` / ``mem_writel_phys`` 64 | :header-rows: 1 65 | :widths: 1 999 66 | 67 | * - Parameter 68 | - Description 69 | 70 | * - ``addr`` 71 | - 32-bit memory address to write. 72 | 73 | * - ``val`` 74 | - 8- (``mem_readb_phys``), 16- (``mem_readw_phys``) or 32-bit (``mem_readl_phys``) value to write to the given memory address. 75 | -------------------------------------------------------------------------------- /dev/api/images/deviceconfig.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/dev/api/images/deviceconfig.png -------------------------------------------------------------------------------- /dev/api/images/pciint.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/dev/api/images/pciint.png -------------------------------------------------------------------------------- /dev/api/index.rst: -------------------------------------------------------------------------------- 1 | API 2 | === 3 | 4 | This section documents the internal **Application Programming Interface** for extending 86Box. 5 | 6 | .. toctree:: 7 | :maxdepth: 1 8 | 9 | device 10 | timer 11 | thread 12 | io 13 | dma 14 | pci 15 | -------------------------------------------------------------------------------- /dev/api/io.rst: -------------------------------------------------------------------------------- 1 | Port I/O 2 | ======== 3 | 4 | 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``. 5 | 6 | .. flat-table:: ``io_sethandler`` / ``io_removehandler`` 7 | :header-rows: 1 8 | :widths: 1 999 9 | 10 | * - Parameter 11 | - Description 12 | 13 | * - ``base`` 14 | - First I/O port (0x0000-0xffff) covered by this handler. 15 | 16 | * - ``size`` 17 | - Amount of I/O ports (1-65536) covered by this handler, starting at ``base``. 18 | 19 | * - ``inb`` 20 | - :rspan:`2` I/O read operation callback functions. Can be ``NULL``. Each callback takes the form of: 21 | 22 | ``TYPE callback(uint16_t addr, void *priv)`` 23 | 24 | * ``TYPE``: operation width: ``uint8_t`` for ``inb``, ``uint16_t`` for ``inw``, ``uint32_t`` for ``inl``; 25 | * ``addr``: exact I/O port being read; 26 | * ``priv``: opaque pointer (see ``priv`` below); 27 | * Return value: 8- (``inb``), 16- (``inw``) or 32-bit (``inl``) value read from this port. 28 | 29 | * - ``inw`` 30 | 31 | * - ``inl`` 32 | 33 | * - ``outb`` 34 | - :rspan:`2` I/O write operation callback functions. Can be ``NULL``. Each callback takes the form of: 35 | 36 | ``void callback(uint16_t addr, TYPE val, void *priv)`` 37 | 38 | * ``addr``: exact I/O port being written; 39 | * ``TYPE``: operation width: ``uint8_t`` for ``outb``, ``uint16_t`` for ``outw``, ``uint32_t`` for ``outl``; 40 | * ``val``: 8- (``outb``), 16- (``outw``) or 32-bit (``outl``) value being written to this port; 41 | * ``priv``: opaque pointer (see ``priv`` below). 42 | 43 | * - ``outw`` 44 | 45 | * - ``outl`` 46 | 47 | * - ``priv`` 48 | - Opaque pointer passed to this handler's read/write operation callbacks. 49 | Usually a pointer to a device's :ref:`state structure `. 50 | 51 | I/O handlers can be added or removed at any time, although ``io_removehandler`` must be called with the **exact same** parameters that ``io_sethandler`` was originally called with. For non-Plug and Play devices, you might want to add handlers in the ``init`` callback; for ISA Plug and Play devices, you'd add and/or remove handlers on the ``config_changed`` callback; for PCI devices, you'd do the same whenever the Command register or Base Address (BAR) registers are written to; and so on. 52 | 53 | .. note:: There is no need to call ``io_removehandler`` on the device's ``close`` callback, since a hard reset already removes all I/O handlers. 54 | 55 | Callback fallbacks 56 | ------------------ 57 | 58 | When an I/O handler receives an operation with a width for which it has no callback, the operation will automatically **fall back** to a lower width for which there is a callback. For example, if an ``inl`` operation falls on a handler which has no ``inl`` callback, 86Box will break the operation down to ``inw`` or ``inb`` callbacks on successive port numbers, then combine their return values: 59 | 60 | * ``inl`` callback present:: 61 | 62 | uint32_t val = inl(port); 63 | 64 | * ``inl`` callback not present, but ``inw`` callback present:: 65 | 66 | uint32_t val = inw(port); 67 | val |= (inw(port + 2) << 16); 68 | 69 | * ``inl`` and ``inw`` callbacks not present, but ``inb`` callback present:: 70 | 71 | uint32_t val = inb(port); 72 | val |= (inb(port + 1) << 8); 73 | val |= (inb(port + 2) << 16); 74 | val |= (inb(port + 3) << 24); 75 | 76 | * ``inl``, ``inw`` and ``inb`` callbacks not present:: 77 | 78 | uint32_t val = 0xffffffff; /* don't care */ 79 | 80 | The same rule applies to write callbacks: 81 | 82 | * ``outl`` callback present:: 83 | 84 | uint32_t val = /* ... */; 85 | outl(port, val); 86 | 87 | * ``outl`` callback not present, but ``outw`` callback present:: 88 | 89 | uint32_t val = /* ... */; 90 | outw(port, val & 0xffff); 91 | outw(port + 2, (val >> 16) & 0xffff); 92 | 93 | * ``outl`` and ``outw`` callbacks not present, but ``outb`` callback present:: 94 | 95 | uint32_t val = /* ... */; 96 | outb(port, val & 0xff); 97 | outb(port + 1, (val >> 8) & 0xff); 98 | outb(port + 2, (val >> 16) & 0xff); 99 | outb(port + 3, (val >> 24) & 0xff); 100 | 101 | * ``outl``, ``outw`` and ``outb`` callbacks not present: 102 | 103 | Don't care, no operation performed. 104 | 105 | .. note:: Each broken-down operation triggers the I/O handlers for its respective port number, no matter which handlers are responsible for the starting port number. A handler will **never** receive callbacks for ports outside its ``base`` and ``size`` boundaries. 106 | 107 | This feature's main use cases are devices which store registers that are 8-bit wide but may be accessed with 16- or 32-bit operations: 108 | 109 | .. container:: toggle 110 | 111 | .. container:: toggle-header 112 | 113 | Code example: ``inb`` handler for reading 8-bit registers 114 | 115 | .. code-block:: 116 | 117 | typedef struct { 118 | uint8_t regs[256]; 119 | } foo_t; 120 | 121 | static uint8_t 122 | foo_io_inb(uint16_t addr, void *priv) 123 | { 124 | foo_t *dev = (foo_t *) priv; 125 | return dev->regs[addr & 0xff]; /* register index = I/O port's least significant byte */ 126 | } 127 | 128 | /* No foo_io_inw, so a 16-bit read will read two 8-bit registers in succession. 129 | No foo_io_inl, so a 32-bit read will read four 8-bit registers in succession. */ 130 | 131 | Multiple I/O handlers 132 | --------------------- 133 | 134 | Any given I/O port can have an **unlimited** amount of I/O handlers, such that: 135 | 136 | * when a **read** operation occurs, all read callbacks will be called, and their return values will be logically **AND**\ ed together; 137 | * when a **write** operation occurs, all write callbacks will be called with the same written value. 138 | 139 | Read callbacks can effectively return "don't care" (without interfering with other handlers) by returning a value with all bits set: ``0xff`` for ``inb``, ``0xffff`` for ``inw`` or ``0xffffffff`` for ``inl``. 140 | 141 | .. note:: The same callback fallback rules specified above also apply with multiple handlers. Handlers without callbacks for the operation's type and (same or lower) width are automatically skipped. 142 | 143 | I/O tracing 144 | ----------- 145 | 146 | The I/O module provides a compile-time option to unconditionally log every port operation performed by the emulated machine. Add ``#define ENABLE_IO_LOG 1`` to the top of ``src/io.c`` to enable global I/O tracing. 147 | 148 | One trace entry is output per line, formatted as such:: 149 | 150 | [E000:0000C0A6] (0, 1, 0001) in b(0061) = 2C 151 | [E000:0000C0AC] (0, 0, 0000) outb(00EB, 3C) 152 | [E000:0000C16A] (0, 2, 0002) outl(C808, 000CF000) 153 | [E000:0000C142] (0, 1, 0002) in w(C400) = 0000 154 | [E000:0000C15E] (0, 2, 0001) outw(C400, 0001) 155 | 156 | * In brackets: current ``CS:(E)IP``, pointing past the I/O instruction 157 | * In parentheses: 158 | 159 | * SMM flag: **1** if the CPU is in System Management Mode, **0** otherwise 160 | * Handler types found: as byte widths **OR**\ ed together; for example, 3 indicates both 8-bit (1) and 16-bit (2) handlers were found for this port 161 | * Call count: total amount of callbacks called in this operation; fallbacks count as multiple calls 162 | 163 | * Operation type: ``in`` or ``out`` followed by ``b``, ``w`` or ``l`` 164 | * Port being accessed (in hexadecimal) 165 | * Value being read or written (in hexadecimal) 166 | 167 | .. note:: I/O tracing incurs a heavy load on stderr output, which can bottleneck emulation to a near halt in I/O-heavy workloads (such as POST) when outputting to a terminal. Using the ``-L`` command line option to redirect logging to a file on solid state storage is highly recommended. 168 | 169 | I/O traps 170 | --------- 171 | 172 | A second type of I/O handler, **I/O traps** allow a device (usually System Management Mode on chipsets or legacy compatibility mechanisms on PCI sound cards) to act upon a read/write operation to an I/O port operation without affecting its result. 173 | 174 | .. container:: toggle 175 | 176 | .. container:: toggle-header 177 | 178 | Code example: I/O trap on ports ``0x220``-``0x22f`` 179 | 180 | .. code-block:: 181 | 182 | typedef struct { 183 | void *trap_220; 184 | } foo_t; 185 | 186 | static void 187 | foo_trap_220(int size, uint16_t addr, uint8_t write, uint8_t val, void *priv) 188 | { 189 | /* Get the device state structure. */ 190 | foo_t *dev = (foo_t *) priv; 191 | 192 | /* Do whatever you want. */ 193 | pclog("Foo: Trapped I/O %s to port %04X, size %d\n", 194 | write ? "write" : "read", addr, size); 195 | if (write) 196 | pclog("Foo: Written value: %02X\n", val); 197 | } 198 | 199 | static void * 200 | foo_init(const device_t *info) 201 | { 202 | /* Allocate the device state structure. */ 203 | foo_t *dev = /* ... */ 204 | 205 | /* Add I/O trap. */ 206 | dev->trap_220 = io_trap_add(foo_trap_220, dev); 207 | 208 | /* Map I/O trap to 16 ports starting at 0x220. */ 209 | io_trap_remap(dev->trap_220, 1, 0x220, 16); 210 | 211 | return dev; 212 | } 213 | 214 | static void 215 | foo_close(void *priv) 216 | { 217 | /* Get the device state structure. */ 218 | foo_t *dev = (foo_t *) priv; 219 | 220 | /* Remove I/O trap before deallocating the device state structure. */ 221 | io_trap_remove(dev->trap_220); 222 | free(dev); 223 | } 224 | 225 | const device_t foo4321_device = { 226 | /* ... */ 227 | .init = foo_init, 228 | .close = foo_close, 229 | /* ... */ 230 | }; 231 | 232 | .. flat-table:: ``io_trap_add`` 233 | :header-rows: 1 234 | :widths: 1 999 235 | 236 | * - Parameter 237 | - Description 238 | 239 | * - ``func`` 240 | - Function called whenever an I/O operation of any type or size is performed to the trap's I/O address range. Takes the form of: 241 | 242 | ``void func(int size, uint16_t addr, uint8_t write, uint8_t val, void *priv)`` 243 | 244 | * ``size``: I/O operation width: ``1``, ``2`` or ``4``; 245 | * ``addr``: I/O address the operation is being performed on; 246 | * ``write``: ``0`` if this operation is a *read*, or ``1`` if it's a *write*; 247 | * ``val``: value being written if this operation is a write; 248 | * ``priv``: opaque pointer (see ``priv`` below). 249 | 250 | * - ``priv`` 251 | - Opaque pointer passed to the ``func`` callback above. 252 | Usually a pointer to a device's :ref:`state structure `. 253 | 254 | * - **Return value** 255 | - Opaque (``void``) pointer representing the newly-created I/O trap. 256 | 257 | .. flat-table:: ``io_trap_remap`` 258 | :header-rows: 1 259 | :widths: 1 999 260 | 261 | * - Parameter 262 | - Description 263 | 264 | * - ``trap`` 265 | - Opaque pointer representing the I/O trap to remap. 266 | 267 | * - ``enable`` 268 | - * ``1`` to enable this trap; 269 | * ``0`` to disable it. 270 | 271 | * - ``addr`` 272 | - First I/O port (0x0000-0xffff) covered by this trap. 273 | 274 | * - ``size`` 275 | - Amount of I/O ports (1-65536) covered by this trap. 276 | -------------------------------------------------------------------------------- /dev/api/thread.rst: -------------------------------------------------------------------------------- 1 | Threads 2 | ======= 3 | 4 | Compute-intensive tasks can be offloaded from the main emulation flow with **threads**. Unless otherwise stated, all structures, functions and constants in this page are provided by ``86box/plat.h``. 5 | 6 | .. warning:: 86Box API functions (excluding those in this page) are generally **not thread-safe** and must be called from the **main emulation thread**. Thread-unsafe actions (such as raising an interrupt) can be performed by the callback of a free-running :doc:`timer ` which looks for data written to the device's :ref:`state structure ` by a thread, as timers run on the main emulation thread. 7 | 8 | .. note:: The contents of ``thread_t`` and other structures used by ``thread_*`` functions are platform-specific; therefore, pointers to those structures should be treated as opaque pointers. 9 | 10 | Starting 11 | -------- 12 | 13 | Threads can be started with the ``thread_create`` function. Additionally, the ``thread_wait`` function can be used to wait for a thread's function to return. 14 | 15 | .. flat-table:: ``thread_create`` 16 | :header-rows: 1 17 | :widths: 1 999 18 | 19 | * - Parameter 20 | - Description 21 | 22 | * - ``thread_func`` 23 | - Function to run in the thread. Takes the form of: 24 | 25 | ``void thread_func(void *priv)`` 26 | 27 | * ``priv``: opaque pointer (see ``priv`` below). 28 | 29 | * - ``priv`` 30 | - Opaque pointer passed to the ``thread_func`` above. 31 | Usually a pointer to a device's :ref:`state structure `. 32 | 33 | * - **Return value** 34 | - ``thread_t`` pointer representing the newly-created thread. 35 | That pointer will become **invalid** once the thread's function returns. 36 | 37 | .. flat-table:: ``thread_wait`` 38 | :header-rows: 1 39 | :widths: 1 999 40 | 41 | * - Parameter 42 | - Description 43 | 44 | * - ``arg`` 45 | - ``thread_t`` pointer representing the thread to wait for. 46 | 47 | * - **Return value** 48 | - * ``0`` on success; 49 | * Any other value on failure. 50 | 51 | Events 52 | ------ 53 | 54 | **Events** allow for synchronization between threads. An event, represented by an ``event_t`` pointer returned by the ``thread_create_event`` function, can be *set* (``thread_set_event`` function) or *reset* (``thread_reset_event`` function), and a thread can wait for an event to be *set* with the ``thread_wait_event`` function. Events that are no longer to be used should be deallocated with the ``thread_destroy_event`` function. 55 | 56 | .. flat-table:: ``thread_create_event`` 57 | :header-rows: 1 58 | :widths: 1 999 59 | 60 | * - Parameter 61 | - Description 62 | 63 | * - **Return value** 64 | - ``event_t`` pointer representing the newly-created event. 65 | 66 | .. flat-table:: ``thread_set_event`` / ``thread_reset_event`` / ``thread_destroy_event`` 67 | :header-rows: 1 68 | :widths: 1 999 69 | 70 | * - Parameter 71 | - Description 72 | 73 | * - ``arg`` 74 | - ``event_t`` pointer representing the event to *set* (``thread_set_event``), *reset* (``thread_reset_event``) or deallocate (``thread_destroy_event``). 75 | 76 | .. flat-table:: ``thread_wait_event`` 77 | :header-rows: 1 78 | :widths: 1 999 79 | 80 | * - Parameter 81 | - Description 82 | 83 | * - ``arg`` 84 | - ``event_t`` pointer representing the event to wait for. 85 | 86 | * - ``timeout`` 87 | - Maximum amount of time in **milliseconds** (not microseconds, unlike :doc:`timers `) to spend waiting for this event to be *set*. If set to ``-1``, this function will not return until the event is *set*. 88 | 89 | * - **Return value** 90 | - * ``0`` on success; 91 | * Any other value if ``timeout`` was reached or the wait otherwise failed. 92 | 93 | .. note:: A ``thread_wait_event`` call does not *reset* the event once it is *set*; the event must be *reset* manually with ``thread_reset_event``. ``thread_wait_event`` returns immediately if the event is already *set*. 94 | 95 | Mutexes 96 | ------- 97 | 98 | `Mutexes `_, also known as **locks**, can control access to a shared resource, ensuring no concurrent modifications or other issues arise from multiple threads attempting to use the same resource at the same time. A mutex, represented by a ``mutex_t`` pointer returned by the ``thread_create_mutex`` function, can be *locked* with the ``thread_wait_mutex`` function (which waits until the mutex is *released*) and *released* with the ``thread_release_mutex`` function. Additionally, the status of a mutex can be independently checked with the ``thread_test_mutex`` function. Mutexes that are no longer to be used should be deallocated with the ``thread_close_mutex`` function. 99 | 100 | .. flat-table:: ``thread_create_mutex`` 101 | :header-rows: 1 102 | :widths: 1 999 103 | 104 | * - Parameter 105 | - Description 106 | 107 | * - **Return value** 108 | - ``mutex_t`` pointer representing the newly-created mutex. 109 | 110 | .. flat-table:: ``thread_wait_mutex`` / ``thread_release_mutex`` / ``thread_close_mutex`` 111 | :header-rows: 1 112 | :widths: 1 999 113 | 114 | * - Parameter 115 | - Description 116 | 117 | * - ``arg`` 118 | - ``mutex_t`` pointer representing the mutex to *lock* (``thread_wait_mutex``), *release* (``thread_release_mutex``) or deallocate (``thread_close_mutex``). 119 | If this mutex is locked, ``thread_wait_mutex`` will not return until the mutex is *released* by another thread. 120 | 121 | .. flat-table:: ``thread_test_mutex`` 122 | :header-rows: 1 123 | :widths: 1 999 124 | 125 | * - Parameter 126 | - Description 127 | 128 | * - ``arg`` 129 | - ``mutex_t`` pointer representing the mutex to check. 130 | 131 | * - **Return value** 132 | - * ``0`` if this mutex is *locked*; 133 | * Any other value if the mutex is *released*. 134 | -------------------------------------------------------------------------------- /dev/api/timer.rst: -------------------------------------------------------------------------------- 1 | Timers 2 | ====== 3 | 4 | **Timers** allow devices to perform tasks after a set period. This period is **automatically scaled** to match the emulation speed, which helps 86Box stay relatively accurate, unlike other emulators and virtualizers which may operate timers in real time independently of speed. Unless otherwise stated, all structures, functions and constants in this page are provided by ``86box/timer.h``. 5 | 6 | .. note:: Timers are processed after each CPU instruction in interpreter mode, or each recompiled code block in dynamic recompiler mode (unless an instruction requests a Time Stamp Counter (TSC) update). In both cases, timer accuracy **should** be in the single-digit microsecond range at a minimum, which is good enough for most time-sensitive applications such as 48 KHz audio. 7 | 8 | Adding 9 | ------ 10 | 11 | Timers can be added with the ``timer_add`` function. The best place for adding a timer is in a :doc:`device `'s ``init`` callback, storing the ``pc_timer_t`` object in the :ref:`state structure `. 12 | 13 | .. container:: toggle 14 | 15 | .. container:: toggle-header 16 | 17 | Code example: adding a timer 18 | 19 | .. code-block:: 20 | 21 | #include <86box/device.h> 22 | #include <86box/timer.h> 23 | 24 | typedef struct { 25 | pc_timer_t countdown_timer; 26 | } foo_t; 27 | 28 | /* Called once the timer period is reached. */ 29 | static void 30 | foo_countdown_timer(void *priv) 31 | { 32 | /* Get the device state structure. */ 33 | foo_t *dev = (foo_t *) priv; 34 | 35 | /* Do whatever you want. */ 36 | } 37 | 38 | static void * 39 | foo_init(const device_t *info) 40 | { 41 | /* Allocate the device state structure. */ 42 | foo_t *dev = /* ... */ 43 | 44 | /* Add timer. */ 45 | timer_add(&dev->countdown_timer, foo_countdown_timer, foo, 0); 46 | } 47 | 48 | const foo1234_device = { 49 | /* ... */ 50 | .init = foo_init, 51 | /* ... */ 52 | }; 53 | 54 | .. flat-table:: ``timer_add`` 55 | :header-rows: 1 56 | :widths: 1 999 57 | 58 | * - Parameter 59 | - Description 60 | 61 | * - ``timer`` 62 | - Pointer to a ``pc_timer_t`` object stored somewhere, usually in a device's :ref:`state structure `. 63 | 64 | * - ``callback`` 65 | - Function called every time the timer's period is reached. Takes the form of: 66 | 67 | ``void callback(void *priv)`` 68 | 69 | * ``priv``: opaque pointer (see ``priv`` below). 70 | 71 | * - ``priv`` 72 | - Opaque pointer passed to the ``callback`` above. 73 | Usually a pointer to a device's :ref:`state structure `. 74 | 75 | * - ``start_timer`` 76 | - Part of the :ref:`legacy API `, should always be ``0``. 77 | 78 | Triggering 79 | ---------- 80 | 81 | The ``timer_on_auto`` function can be used to start (with the provided microsecond period) or stop a timer. It can also be called from a timer callback to restart the timer: 82 | 83 | .. container:: toggle 84 | 85 | .. container:: toggle-header 86 | 87 | Code example: starting, restarting and stopping a timer 88 | 89 | .. code-block:: 90 | 91 | #include <86box/timer.h> 92 | 93 | typedef struct { 94 | uint8_t regs[256]; 95 | pc_timer_t countdown_timer; /* don't forget to timer_add on init, per the example above */ 96 | } foo_t; 97 | 98 | static void 99 | foo_countdown_timer(void *priv) 100 | { 101 | /* Get the device state structure. */ 102 | foo_t *dev = (foo_t *) priv; 103 | 104 | /* Restart timer automatically if the relevant 105 | bit (see register description below) is set. */ 106 | if (dev->regs[0x80] & 0x02) 107 | timer_on_auto(&dev->countdown_timer, 100.0); 108 | } 109 | 110 | /* Our device handles I/O port register 0x__80 like this: 111 | - Bit 0 (0x01) set: start 100-microsecond countdown timer; 112 | - Bit 0 (0x01) clear: stop countdown timer; 113 | - Bit 1 (0x02) set: automatically restart timer. */ 114 | static void 115 | foo_outb(uint16_t addr, uint8_t val, void *priv) 116 | { 117 | /* Get the device state structure. */ 118 | foo_t *dev = (foo_t *) priv; 119 | 120 | /* Handle writes to register 0x80. */ 121 | if ((addr & 0xff) == 0x80) { 122 | dev->regs[0x80] = val; 123 | if (val & 0x01) /* bit 0 set */ 124 | timer_on_auto(&dev->countdown_timer, 100.0); 125 | else /* bit 0 clear */ 126 | timer_on_auto(&dev->countdown_timer, 0.0); 127 | } 128 | } 129 | 130 | .. flat-table:: ``timer_on_auto`` 131 | :header-rows: 1 132 | :widths: 1 999 133 | 134 | * - Parameter 135 | - Description 136 | 137 | * - ``timer`` 138 | - Pointer to the timer's ``pc_timer_t`` object. 139 | 140 | * - ``period`` 141 | - Period after which the timer callback is called, in microseconds (1/1,000,000th of a second or 1/1,000th of a millisecond) as a ``double``. 142 | A period of ``0.0`` stops the timer if it's active. 143 | 144 | Legacy API 145 | ---------- 146 | 147 | Existing devices may use the ``timer_set_delay_u64`` and ``timer_advance_u64`` functions, which are considered legacy and will not be documented here for simplicity. These functions used an internal 64-bit period unit, which had to be obtained by multiplying the microsecond value by the ``TIMER_USEC`` constant, and updated by the device's ``speed_changed`` callback. The new ``timer_on_auto`` function is much simpler, requiring no constant multiplication or updates. 148 | -------------------------------------------------------------------------------- /dev/buildguide.rst: -------------------------------------------------------------------------------- 1 | Build guide 2 | =========== 3 | 4 | 86Box is built using `CMake `_ in combination with other build systems. The build actions are described in ``CMakeLists.txt`` files in most directories, which are the translated to the build system of choice by a CMake generator. 5 | 6 | The following files are of particular interest: 7 | 8 | * ``./CMakeLists.txt`` is the top level file, which defines the 86Box project and available configuration options; 9 | * ``./src/CMakeLists.txt`` defines the main 86Box executable target 10 | 11 | Toolchain files 12 | --------------- 13 | 14 | Toolchain files are contained in the ``cmake`` directory. They define compiler flags and the 86Box-specific ``Release``, ``Debug`` and ``Optimized`` build types. 15 | 16 | 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. 17 | 18 | The currently included files are: 19 | 20 | * ``flags-gcc.cmake`` contains the generic flags used by GCC-like compilers 21 | 22 | * ``flags-gcc-.cmake`` includes flags specific to builds for a given architecture 23 | 24 | * ``llvm-win32-.cmake`` defines the build environment for use with LLVM/clang and vcpkg on Windows 25 | 26 | Toolchain files are consumed during the initial project generation stage by passing their path in the ``CMAKE_TOOLCHAIN_FILE`` variable, e.g.: 27 | 28 | .. code-block:: bash 29 | 30 | $ cmake … -D CMAKE_TOOLCHAIN_FILE=./cmake/flags-gcc-x86_64.cmake 31 | 32 | .. note:: When using vcpkg, which uses its own toolchain file, the 86Box toolchain files must be chainloaded using the ``VCPKG_CHAINLOAD_TOOLCHAIN_FILE`` variable. 33 | 34 | Presets 35 | ------- 36 | 37 | The ``CMakePresets.json`` file contains several common compilation options for 86Box: 38 | 39 | .. list-table:: 40 | :header-rows: 1 41 | 42 | * - Build name 43 | - Debug 44 | - Dev. branch 45 | - Optimized 46 | * - ``regular`` 47 | - ❌ 48 | - ❌ 49 | - ❌ 50 | * - ``development`` 51 | - ❌ 52 | - ✅ 53 | - ❌ 54 | * - ``debug`` 55 | - ✅ 56 | - ❌ 57 | - ❌ 58 | * - ``dev_debug`` 59 | - ✅ 60 | - ✅ 61 | - ❌ 62 | * - ``optimized`` 63 | - ❌ 64 | - ❌ 65 | - ✅ 66 | 67 | The presets are consumed during the initial project generation stage by using the ``--preset`` CMake command line option, e.g.: 68 | 69 | .. code-block:: bash 70 | 71 | $ cmake … --preset regular 72 | 73 | .. note:: Presets require CMake 3.21 or newer. 74 | 75 | Obtaining the source code 76 | ------------------------- 77 | 78 | There are multiple ways to obtain the 86Box source code in order to build it: 79 | 80 | * Use the ``git`` command line. The utility needs to be installed and present in the search path. 81 | 82 | .. code-block:: bash 83 | 84 | $ git clone https://github.com/86Box/86Box.git 85 | 86 | * Use GitHub Desktop, SourceTree, Git for Windows or other Git frontend on your host. 87 | 88 | * Download a ZIP file from GitHub and extract it. (not recommended) 89 | 90 | Prerequisites 91 | ------------- 92 | 93 | The build process requires the following tools: 94 | 95 | * CMake (>= 3.15) 96 | * ``pkg-config`` 97 | * libatomic 98 | 99 | Development files for the following libraries are also needed: 100 | 101 | * FluidSynth 102 | * FreeType 103 | * libpng 104 | * libslirp 105 | * libsndfile 106 | * RtMidi 107 | * SDL2 108 | * OpenAL (by default) or FAudio (installing FAudio is optional on Windows) 109 | * libserialport (optional, needed for external OPL2Board support) 110 | * Qt5 or Qt6 (optional, can be disabled) 111 | 112 | Obtaining the dependencies 113 | ^^^^^^^^^^^^^^^^^^^^^^^^^^ 114 | 115 | MSYS2 116 | """"" 117 | 118 | .. code-block:: bash 119 | 120 | $ pacman -Syu $MINGW_PACKAGE_PREFIX-ninja $MINGW_PACKAGE_PREFIX-cmake $MINGW_PACKAGE_PREFIX-gcc $MINGW_PACKAGE_PREFIX-pkgconf $MINGW_PACKAGE_PREFIX-openal $MINGW_PACKAGE_PREFIX-freetype $MINGW_PACKAGE_PREFIX-SDL2 $MINGW_PACKAGE_PREFIX-zlib $MINGW_PACKAGE_PREFIX-libpng $MINGW_PACKAGE_PREFIX-rtmidi $MINGW_PACKAGE_PREFIX-fluidsynth $MINGW_PACKAGE_PREFIX-libslirp $MINGW_PACKAGE_PREFIX-libsndfile $MINGW_PACKAGE_PREFIX-qt5-static $MINGW_PACKAGE_PREFIX-qt5-translations $MINGW_PACKAGE_PREFIX-vulkan-headers 121 | 122 | .. note:: The command installs the packages only for the currently used MinGW environment, therefore you will need to repeat the procedure for every target you plan to build for. 123 | 124 | Ubuntu, Debian 125 | """""""""""""" 126 | 127 | .. code-block:: bash 128 | 129 | $ sudo apt install build-essential cmake extra-cmake-modules pkg-config ninja-build libfreetype-dev libsdl2-dev libpng-dev libopenal-dev librtmidi-dev libfluidsynth-dev libsndfile1-dev libserialport-dev qtbase5-dev qtbase5-private-dev qttools5-dev libevdev-dev libxkbcommon-dev libxkbcommon-x11-dev libslirp-dev 130 | 131 | 132 | Arch 133 | """" 134 | 135 | .. code-block:: bash 136 | 137 | $ sudo pacman -Sy base-devel cmake extra-cmake-modules pkgconf ninja libfreetype sdl2 libpng openal rtmidi libslirp fluidsynth libsndfile libserialport qt5-base qt5-xcb-private-headers qt5-tools libevdev libxkbcommon libxkbcommon-x11 vulkan-devel 138 | 139 | 140 | Fedora 141 | """""" 142 | 143 | .. code-block:: bash 144 | 145 | $ sudo dnf groupinstall "C Development Tools and Libraries" 146 | $ sudo dnf install cmake extra-cmake-modules pkg-config ninja-build freetype-devel SDL2-devel libatomic libpng-devel libslirp-devel libXi-devel openal-soft-devel rtmidi-devel fluidsynth-devel libsndfile-devel libserialport-devel qt5-linguist qt5-qtconfiguration-devel qt5-qtbase-private-devel qt5-qtbase-static wayland-devel libevdev-devel libxkbcommon-x11-devel zlib-ng-compat-static 147 | 148 | 149 | macOS (Homebrew) 150 | """""""""""""""" 151 | 152 | .. code-block:: bash 153 | 154 | $ brew install cmake ninja pkg-config freetype sdl2 libpng openal-soft rtmidi libslirp fluid-synth libsndfile libserialport qt@5 155 | 156 | 157 | FreeBSD 158 | """"""" 159 | 160 | .. code-block:: bash 161 | 162 | $ pkg install pkgconf freetype-gl sdl2 libspng openal-soft rtmidi qt5 libslirp fluidsynth libsndfile 163 | 164 | .. 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. 165 | 166 | Building 167 | -------- 168 | 169 | Building 86Box can generally be condensed to the following steps: 170 | 171 | 1. Generate the project. This generally involves invoking the following base command line with additional options according to the development environment: 172 | 173 | .. code-block:: bash 174 | 175 | $ cmake -B -S 176 | 177 | 178 | Build directory is where the resulting binaries and other build artifacts will be stored. Source directory is the location of the 86Box source code. 179 | 180 | Toolchain files and presets are specified at this point by using the respective options. 181 | 182 | Other options can be specified using the ``-D`` option, e.g. ``-D NEW_DYNAREC=ON`` enables the new dynamic recompiler. See ``CMakeLists.txt`` in the root of the repository for the full list of available options. 183 | 184 | 2. Build the project itself. This can be done by changing to the chosen build directory and invoking the chosen build system, or you can use the following universal CMake command: 185 | 186 | .. code-block:: bash 187 | 188 | $ cmake --build 189 | 190 | Appending the ``-jN`` option (where ``N`` is a number of threads you want to use for the compilation process) will run the build on multiple threads, speeding up the process some. 191 | 192 | .. note:: If you make changes to the CMake build files, running the command will automatically regenerate the project. There is no need to repeat step 1 or to delete the build directory. 193 | 194 | 3. If everything succeeds, you should find the resulting executable in the build directory. Depending on the build system, it might be located in some of its subdirectories. 195 | 196 | .. tip:: The executable can be copied to a consistent location by running the following command: 197 | 198 | .. code-block:: bash 199 | 200 | $ cmake --install --prefix 201 | 202 | The emulator file should then be copied into a ``bin`` directory in the specified location. 203 | 204 | Appending the ``--strip`` parameter will also strip debug symbols from the executable in the process. 205 | -------------------------------------------------------------------------------- /dev/builds.rst: -------------------------------------------------------------------------------- 1 | Advanced builds 2 | =============== 3 | 4 | The `86Box Jenkins `_ provides all kinds of pre-release testing builds for advanced users. These are linked to the `86Box git repository on GitHub `_; a new build is produced with the latest source code every time the repository is updated. 5 | 6 | .. important:: Testing builds are development snapshots which may contain bugs, unfinished features or other issues. These should only be used if you know what you're doing. 7 | 8 | Variants 9 | -------- 10 | 11 | 86Box builds are available in a number of variants. The Jenkins page will automatically detect the recommended variant for the system you're viewing it on, but if you're downloading builds for a different system (or you have disabled JavaScript), use the guide below to select a variant: 12 | 13 | * The **Old Recompiler** is recommended. The **New Recompiler** is in beta; you may experience bugs and performance loss with it. 14 | 15 | * The Old Recompiler is not available for the ARM architecture. You must select the New Recompiler for running 86Box on ARM Linux systems. 16 | 17 | * On **Windows**, **x64** is the only option, as native ARM builds are currently not provided. 18 | 19 | * On **Linux**, select **x64** or **ARM** according to your system's architecture. 20 | 21 | * On **macOS**, **Universal** supports both Intel and Apple Silicon Macs. 22 | 23 | * The New Recompiler is always used on Apple Silicon due to its ARM architecture, even if the Old Recompiler is selected. 24 | 25 | Discontinued variants 26 | ^^^^^^^^^^^^^^^^^^^^^ 27 | 28 | These variants are no longer built by Jenkins and can only be :doc:`compiled from source `. 29 | 30 | * 32-bit variants (**x86** and **ARM32**) as of September 3rd 2024. 31 | 32 | * These variants 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. 33 | 34 | * Debug variants (**86Box-Debug**) as of April 2nd 2023. 35 | 36 | * These variants were compiled with debug symbols and reduced optimizations to help with running the emulator under ``gdb`` or other debuggers. They were eliminated as the setup process for debugging grew closer to just compiling from source instead. 37 | 38 | * Dev variants (**86Box-Dev** and **86Box-DevODR**) as of November 18th 2021. 39 | 40 | * These variants contained incomplete and experimental features subject to change at any time, with the -Dev variant also containing the New Recompiler beta. 41 | 42 | * Optimized variants (**86Box-Optimized**) as of March 18th 2021. 43 | 44 | * These variants' aggressive microarchitecture-specific optimizations provided very little performance improvement (within margin of error on modern CPUs) while introducing bugs and other incorrect behavior. 45 | -------------------------------------------------------------------------------- /dev/formats/86f.rst: -------------------------------------------------------------------------------- 1 | 86F 2 | === 3 | 4 | A floppy disk surface image format which stores data in FM- or MFM-encoded transitions. 5 | 6 | Specification for v2.12 7 | ----------------------- 8 | 9 | All offsets are in hexadecimal. 10 | 11 | .. code-block:: none 12 | 13 | 00000000: Magic 4 bytes ("86BF") 14 | 00000004: Minor version (0C) 15 | 00000005: Major version (02) 16 | 00000006: Disk flags (16-bit) 17 | Bit 0 Has surface description data (1 = yes, 0 = no) 18 | This data indicates if the corresponding bit on the FM/MFM 19 | encoded surface is a normal bit or a special bit (weak bit 20 | or hole, depending on the other bit): 21 | 0 = The corresponding FM/MFM encoded surface bit is normal 22 | 1 = The corresponding FM/MFM encoded surface bit is either 23 | a weak bit or a hole: 24 | Corresponding FM/MFM encoded bit is 0: 25 | Hole (noise on read, not overwritable) 26 | Corresponding FM/MFM encoded bit is 1: 27 | Weak bit (noise on read, overwritable) 28 | Bits 2, 1 Hole (3 = ED + 2000 kbps, 2 = ED, 1 = HD, 0 = DD) 29 | Bit 3 Sides (1 = 2 sides, 0 = 1 side) 30 | Bit 4 Write protect (1 = yes, 0 = no) 31 | Bits 6, 5 RPM slowdown (3 = 2%, 2 = 1.5%, 1 = 1%, 0 = 0%) 32 | Bit 7 Bitcell mode (1 = Extra bitcells count specified after 33 | disk flags, 0 = No extra bitcells) 34 | The maximum number of extra bitcells is 1024 (which 35 | after decoding translates to 64 bytes) 36 | Bit 8 Disk type (1 = Zoned, 0 = Fixed RPM) 37 | Bits 10, 9 Zone type (3 = Commodore 64 zoned, 2 = Apple zoned, 38 | 1 = Pre-Apple zoned #2, 0 = Pre-Apple zoned #1) 39 | Ignore if disk type is 0 (fixed RPM) 40 | Bit 11 Data and surface bits are stored in reverse byte endianness 41 | Bit 12 If set: 42 | If bits 6, 5 are not 0, they specify % of speedup instead 43 | of slowdown; 44 | If bits 6, 5 are 0, and bit 7 is 1, the extra bitcell count 45 | specifies the entire bitcell count 46 | For converting other stuff to 86F, I recommend to set this bit 47 | and bit 7 and clear bits 6 and 5, 48 | and just specify the entire bitcell count. 49 | 00000008: Offsets of tracks 50 | Note that thick-track (eg. 360k) disks will have (tracks * 2) tracks, with each 51 | pair of tracks being identical to each other. 52 | Each side of each track is stored as its own track, in order (so, track 0 side 0, 53 | track 0 side 1, track 1 side 0, track 1 side 0, etc.). 54 | 55 | Track offset + 00000000: Track flags (16-bit) 56 | Bits 7, 6, 5 RPM: 57 | 000 = 300 rpm 58 | 001 = 360 rpm 59 | Bits 4, 3 Encoding: 60 | 00 = FM 61 | 01 = MFM 62 | 10 = M2FM 63 | 11 = GCR 64 | Bits 2, 1, 0 Bit rate, if encoding is MFM: 65 | 000 = 500 kbps 66 | 001 = 300 kbps 67 | 010 = 250 kbps 68 | 011 = 1000 kbps 69 | 101 = 2000 kbps 70 | If encoding is FM, the bit rate is half that. 71 | If the bitcell count is present: 72 | Track offset + 00000002: Extra (or total, depending on disk flags) bit cells count (32-bit) 73 | If this specifies extra bit cells rather than total, it is a signed 74 | integer, and when negative, makes the track smaller. 75 | Track offset + 00000006: Bit cell where index hole is (32-bit) 76 | Track offset + 0000000A: FM/MFM/M2FM/GCR-encoded data (track length bytes) 77 | Track offset + 0000000A + track length: Surface description data if present (track length bytes) 78 | Else: 79 | Track offset + 00000002: Bit cell where index hole is (32-bit) 80 | Track offset + 00000006: FM/MFM/M2FM/GCR-encoded data (track length bytes) 81 | Track offset + 00000006 + track length: Surface description data if present (track length bytes) 82 | 83 | Track lengths if the bitcell count is not present or it does not represent total bit cells: 84 | Hole 0 (DD) or 1 (HD): 85 | 2.0% RPM slowdown: 12750 words 86 | 1.5% RPM slowdown: 12687 words 87 | 1.0% RPM slowdown: 12625 words 88 | 0.0% RPM slowdown/speedup: 12500 words 89 | 1.0% RPM speedup : 12376 words 90 | 1.5% RPM speedup : 12315 words 91 | 2.0% RPM speedup : 12254 words 92 | Hole 2 (ED): 93 | 2.0% RPM slowdown: 25250 words 94 | 1.5% RPM slowdown: 25375 words 95 | 1.0% RPM slowdown: 25250 words 96 | 0.0% RPM slowdown/speedup: 25000 words 97 | 1.0% RPM speedup : 24752 words 98 | 1.5% RPM speedup : 24630 words 99 | 2.0% RPM speedup : 24509 words 100 | Hole 3 (ED + 2000 kbps): 101 | 2.0% RPM slowdown: 51000 words 102 | 1.5% RPM slowdown: 50750 words 103 | 1.0% RPM slowdown: 50500 words 104 | 0.0% RPM slowdown/speedup: 50000 words 105 | 1.0% RPM speedup : 49504 words 106 | 1.5% RPM speedup : 49261 words 107 | 2.0% RPM speedup : 49019 words 108 | 1 word = 2 bytes (so 16 bits) 109 | If extra bit cells count is present and it indicates extra bit cells count: 110 | Track length = (Track length << 4) + Extra bitcells count 111 | If (Track length & 15) 112 | Track length + (Track length >> 4) + 1 113 | Else 114 | Track length + (Track length >> 4) 115 | If extra bit cells count is present and it indicates total bit cells count, 116 | then the total bit cells count become the track length, padded upwards to the 117 | nearest word in the file. 118 | -------------------------------------------------------------------------------- /dev/formats/hdx.rst: -------------------------------------------------------------------------------- 1 | Extended HDI (HDX) 2 | ================== 3 | 4 | A derivative of the *Japanese FDI* disk image format, with a more compact header as well as support for images larger than 4 GB. 5 | 6 | Specification 7 | ------------- 8 | 9 | All offsets are in hexadecimal. The ``[Translation]`` values are for future use. 10 | 11 | .. code-block:: none 12 | 13 | 00000000: Signature (59 54 44 44 20 A8 78 D7 / "YTDD " A8 78 D7) 14 | 00000008: Full size of the data in bytes (64-bit) 15 | 00000010: Sector size in bytes (32-bit) 16 | 00000014: Sectors per cylinder (32-bit) 17 | 00000018: Heads per cylinder (32-bit) 18 | 0000001C: Cylinders (32-bit) 19 | 00000020: [Translation] Sectors per cylinder (32-bit) 20 | 00000024: [Translation] Heads per cylinder (32-bit) 21 | 00000028: Raw data (size set in offset 00000008) 22 | -------------------------------------------------------------------------------- /dev/formats/index.rst: -------------------------------------------------------------------------------- 1 | File formats 2 | ============ 3 | 4 | 86Box introduces new file formats for disk images and other purposes. These formats are documented on this section. 5 | 6 | .. toctree:: 7 | :maxdepth: 1 8 | :caption: Formats 9 | 10 | 86f 11 | hdx 12 | -------------------------------------------------------------------------------- /graphics.pptx: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/graphics.pptx -------------------------------------------------------------------------------- /guides/.gitkeep: -------------------------------------------------------------------------------- 1 | planning to add installation guides here in the not-so-distant future 2 | 3 | - DDX 4 | -------------------------------------------------------------------------------- /hardware/diskimages.rst: -------------------------------------------------------------------------------- 1 | Disk images 2 | =========== 3 | 4 | 86Box supports a large variety of disk image formats for the emulated storage drives. 5 | 6 | .. raw:: html 7 | 8 | 20 | 21 | Hard disk images 22 | ---------------- 23 | 24 | Supported formats: 25 | 26 | .. list-table:: 27 | :header-rows: 1 28 | :widths: 1 1 999 29 | 30 | * - Format 31 | - File extension 32 | - Notes 33 | 34 | * - Raw image 35 | - Many 36 | - Extensions include: .hdd .ima .img 37 | 38 | * - Japanese FDI 39 | - .hdi 40 | - 41 | 42 | * - :doc:`../dev/formats/hdx` 43 | - .hdx 44 | - 45 | 46 | * - Virtual Hard Disk 47 | - .vhd 48 | - Fixed, Dynamic and Differencing VHDs are supported through the `MiniVHD `_ library. 49 | 50 | Hard disk size limits 51 | ^^^^^^^^^^^^^^^^^^^^^ 52 | 53 | There are limits to how big of a hard disk an emulated machine can accept. Such limits will vary depending on the machine's BIOS. The table below lists all important limits applicable to the IDE bus: 54 | 55 | .. list-table:: 56 | :header-rows: 1 57 | 58 | * - Limit 59 | - Disk size 60 | - Cylinders 61 | - Heads 62 | - Sectors 63 | 64 | * - 20-bit CHS 65 | - 504 MB 66 | - 1024 67 | - 16 68 | - 63 69 | 70 | * - 12-bit cylinder 71 | - 2015 MB 72 | - 4095 73 | - 16 74 | - 63 75 | 76 | * - ECHS translation 77 | - 4032 MB 78 | - 1024 79 | - 128 80 | - 63 81 | 82 | * - Revised ECHS 83 | - 7560 MB 84 | - 1024 85 | - 240 86 | - 63 87 | 88 | * - LBA translation 89 | - 8064 MB 90 | - 1024 91 | - 256 92 | - 63 93 | 94 | * - 16-bit cylinder 95 | - 32255 MB 96 | - 65535 97 | - 16 98 | - 63 99 | 100 | * - 28-bit LBA 101 | - 131071 MB 102 | - 65536 103 | - 16 104 | - 256 105 | 106 | Disk overlay software such as the :ref:`settings/storage:Vision Systems LBA Enhancer` or *Ontrack Disk Manager* can work around BIOS limits and allow booting of larger IDE hard drives, with the same caveats as using such software on a real machine. The maximum supported disk image size for IDE or SCSI is 131071 MB. 107 | 108 | Floppy disk images 109 | ------------------ 110 | 111 | Supported formats: 112 | 113 | .. list-table:: 114 | :header-rows: 1 115 | :widths: 1 1 999 116 | 117 | * - Format 118 | - File extension 119 | - Notes 120 | 121 | * - Raw image 122 | - Many 123 | - Extensions include: .bin .dsk .flp .hdm .ima .img .vfd .xdf 124 | 125 | * - :doc:`../dev/formats/86f` 126 | - .86f 127 | - Once loaded, any image can be converted to 86F through the :ref:`status bar ` or :ref:`Media menu `. 128 | 129 | * - CopyQM 130 | - .cq / .cqm 131 | - 132 | 133 | * - DiskDupe 134 | - .ddi 135 | - 136 | 137 | * - EZ-DisKlone plus 138 | - .fdf 139 | - 140 | 141 | * - Formatted Disk Image 142 | - .fdi 143 | - Read only. 144 | 145 | * - HxC MFM 146 | - .mfm 147 | - Read only. 148 | 149 | * - ImageDisk 150 | - .imd 151 | - 152 | 153 | * - Japanese FDI 154 | - .fdi 155 | - 156 | 157 | * - PCjs JSON 158 | - .json 159 | - Read only. 86Box 4.2 added support for the v2 format, replacing v1 which is no longer in circulation. 160 | 161 | * - Teledisk 162 | - .td0 163 | - Read only. 164 | 165 | Floppy disk detection 166 | ^^^^^^^^^^^^^^^^^^^^^ 167 | 168 | 86Box determines the physical media format (sides, tracks per side, sectors per track, bytes per sector) of a floppy disk image through the following methods: 169 | 170 | 1. Image file header data - not applicable for **Raw** and **DiskDupe** formats; 171 | 2. `DOS BIOS Parameter Block `_ data within the image; 172 | 3. If all else fails, a guess is made based on the image file's size. 173 | 174 | The BIOS Parameter Block detection method may behave incorrectly with non-DOS floppy disks. Installation floppies for UNIX and Linux are common examples of non-DOS disks. Disabling :ref:`Check BPB ` is strongly recommended when accessing these, as an inaccurate BPB detection may result in read errors, data corruption and other issues. 175 | 176 | .. note:: When using a **Raw** image of a non-DOS floppy with Check BPB disabled, make sure the image file is not truncated (smaller than its media size), otherwise incorrect behavior may still occur. 177 | 178 | MO / ZIP removable disk images 179 | ------------------------------ 180 | 181 | Supported formats: 182 | 183 | .. list-table:: 184 | :header-rows: 1 185 | :widths: 1 1 999 186 | 187 | * - Format 188 | - File extension 189 | - Notes 190 | 191 | * - Raw image 192 | - Many 193 | - Extensions include: .ima .img 194 | 195 | * - Japanese FDI 196 | - .mdi / .zdi 197 | - .mdi for MO, .zdi for ZIP. 198 | 199 | CD-ROM / DVD-ROM optical disc images 200 | ------------------------------------ 201 | 202 | Supported formats: 203 | 204 | .. list-table:: 205 | :header-rows: 1 206 | :widths: 1 1 999 207 | 208 | * - Format 209 | - File extension 210 | - Notes 211 | 212 | * - Cue sheet 213 | - .cue + .bin (+ optional audio) 214 | - :ref:`Audio tracks are supported. ` 215 | 216 | * - ISO 217 | - .iso 218 | - 219 | 220 | CD audio 221 | ^^^^^^^^ 222 | 223 | Compact Disc Digital Audio (CDDA) playback through the emulated CD-ROM drives is supported on **Cue sheet** images. Audio output is enabled on the first CD-ROM drive and muted on subsequent drives by default; individual drives can be muted or unmuted through the :ref:`status bar ` or :ref:`Media menu `. 224 | 225 | Audio tracks in raw (.bin), encapsulated (.wav) and compressed (.mp3 .ogg .flac .opus) formats are supported. 226 | 227 | Cassette tape images 228 | -------------------- 229 | 230 | Supported formats: 231 | 232 | .. list-table:: 233 | :header-rows: 1 234 | :widths: 1 1 999 235 | 236 | * - Format 237 | - File extension 238 | - Notes 239 | 240 | * - Raw PCM audio 241 | - Many 242 | - Extensions include: .pcm .raw 243 | 244 | Audio format must be unsigned 8-bit mono. 245 | 246 | * - PCE cassette 247 | - .cas 248 | - 249 | 250 | * - Wave audio 251 | - .wav 252 | - Audio format must be unsigned 8-bit mono. 253 | 254 | PCjr cartridge images 255 | --------------------- 256 | 257 | Supported formats: 258 | 259 | .. list-table:: 260 | :header-rows: 1 261 | :widths: 1 1 999 262 | 263 | * - Format 264 | - File extension 265 | - Notes 266 | 267 | * - Raw image 268 | - Many 269 | - Extensions include: .a .b .bin 270 | 271 | * - JRipCart 272 | - .jrc 273 | - 274 | 275 | Creating and using disk images 276 | ------------------------------ 277 | 278 | Disk images are a convenient way to transfer files in and out of emulated machines, without the complexity of setting up networking. There are many different command line and GUI tools available for manipulating disk images on each host operating system. 279 | 280 | .. warning:: Before editing or mounting any disk images, make sure they are **not in use** by any emulated machine that is currently running. 281 | 282 | Editing and mounting on Windows 283 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 284 | 285 | **WinImage** or **PowerISO** can be used to create and manipulate disk images on Windows. 286 | 287 | VHD images can be natively mounted by double-clicking them on File Explorer, or through the **Disk Management** tool (``diskmgmt.msc``): select *Action* > *Attach VHD* to mount an image. Eject the drive through File Explorer to unmount. The ``diskpart`` `command line utility `_ also provides VHD mounting/unmounting functionality. 288 | 289 | Mounting on macOS 290 | ^^^^^^^^^^^^^^^^^ 291 | 292 | macOS can natively mount raw hard disk and floppy images formatted as **FAT** and its variants. Open the image in Finder to mount it, and eject the disk to unmount. 293 | 294 | Editing on Linux and macOS 295 | ^^^^^^^^^^^^^^^^^^^^^^^^^^ 296 | 297 | The `mtools `_ suite is "a collection of utilities to access MS-DOS disks from GNU and Unix without mounting them". It can be used to create floppy disk images and directly copy files to them. The ``mtools`` package is available on many Linux distributions, as well as macOS Homebrew. 298 | 299 | Creating floppy images 300 | ********************** 301 | 302 | The following command will create a 1.44M (1440 KB, double-sided, 18 sectors per track, 80 cylinders) floppy image named ``floppy.img`` with a label of ``LABEL``: 303 | 304 | .. code-block:: 305 | 306 | mformat -f 1440 -v LABEL -C -i floppy.img :: 307 | 308 | The ``-f`` option specifies the format of the floppy being created. The command can be adjusted for format, label, and image name as needed. Refer to the `mtools documentation `_ for a full list of supported formats. 309 | 310 | Copying files to floppy images 311 | ****************************** 312 | 313 | The following command will copy ``file1`` and ``file2`` to the floppy image ``floppy.img``: 314 | 315 | .. code-block:: 316 | 317 | mcopy -i floppy.img file1 file2 :: 318 | 319 | Wildcards are also supported with ``mcopy``. 320 | 321 | .. note:: The ``::`` is required to let ``mtools`` know there are no more files to copy or arguments to process. 322 | 323 | Mounting on Linux 324 | ***************** 325 | 326 | Linux can natively mount raw disk images (floppy or hard disk) of most types (``FAT`` and ``NTFS`` included). The easiest path is to use `losetup `_ so that partitions can be properly recognized. Floppies are not normally partitioned, and you can use `mount `_ directly. 327 | 328 | All following commands must be run as root: 329 | 330 | .. code-block:: sh 331 | 332 | losetup -fP /path/to/86box/hdd 333 | losetup # to verify which loopback device was set up. 334 | # Assuming /dev/loop0 was selected: 335 | mount /dev/loop0p1 /mnt # Mount the first partition at /mnt 336 | 337 | Disk images should at least be unmounted before running 86Box again, and preferably detached too: 338 | 339 | .. code-block:: 340 | 341 | umount /mnt 342 | losetup -d /dev/loop0 343 | 344 | Partitionless media can be mounted directly: 345 | 346 | .. code-block:: 347 | 348 | mount /path/to/86box/fdd /mnt 349 | 350 | VHD images may be mounted via `qemu-nbd `_: 351 | 352 | .. code-block:: 353 | 354 | modprobe nbd max_part=16 355 | qemu-nbd -f vpc -c /dev/nbd0 /path/to/86box/hdd 356 | mount /dev/nbd0p1 /mnt 357 | # After doing some work... 358 | umount /mnt 359 | qemu-nbd -d /dev/nbd0 360 | -------------------------------------------------------------------------------- /hardware/ideterqua.rst: -------------------------------------------------------------------------------- 1 | Tertiary and quaternary IDE 2 | =========================== 3 | 4 | The additional tertiary and quaternary IDE controllers, enabled through the :ref:`Storage controllers ` settings page, are not supported by all emulated BIOSes and may require manual configuration of emulated operating systems. The specific details are outlined on this page. 5 | 6 | System resources 7 | ---------------- 8 | 9 | The following resources are used by these additional controllers: 10 | 11 | +----------+-------------+---------------+---+ 12 | |Channel |Main I/O port|Status I/O port|IRQ| 13 | +==========+=============+===============+===+ 14 | |Tertiary |01E8h |03EEh |11 | 15 | +----------+-------------+---------------+---+ 16 | |Quaternary|0168h |036Eh |10 | 17 | +----------+-------------+---------------+---+ 18 | 19 | .. note:: The tertiary and quaternary I/O ports and IRQs were incorrectly switched in 86Box versions prior to 4.0.1. 20 | 21 | Each controller's IRQ can be configured through its respective *Settings* button on :ref:`settings/storage:Tertiary / Quaternary IDE Controller`. The *Plug and Play* option on the *IRQ* box enables Plug and Play functionality, allowing a PnP compliant operating system to automatically set the controller's IRQ, while all other options set a static IRQ with no Plug and Play. 22 | 23 | .. note:: * When using a non-Plug and Play IDE controller on an emulated machine which supports Plug and Play, remember to mark the IRQ as being used by a legacy ISA device in the BIOS setup utility. 24 | * Many operating systems do not allow non-Plug and Play IDE controllers to use IRQs outside of the default ones listed on the table above. 25 | 26 | BIOS support 27 | ------------ 28 | 29 | The tertiary and quaternary controllers are not visible and not bootable by the BIOS on most machines currently emulated by 86Box, no matter whether or not they are Plug and Play. 30 | 31 | Machines with **MR BIOS version 3** are the rare exception to this rule, since that BIOS provides full support for non-Plug and Play controllers (as long as the :ref:`default IRQs for each controller ` are used), including bootability and INT 13h services. 32 | 33 | Operating system support 34 | ------------------------ 35 | 36 | DOS and real mode 37 | ^^^^^^^^^^^^^^^^^ 38 | 39 | **DOS and other real mode operating systems** rely on INT 13h services provided by the BIOS to access hard disks. These are only provided for the tertiary and quaternary channels by **MR BIOS version 3**, as mentioned above. 40 | 41 | Windows 95, 98 and Me 42 | ^^^^^^^^^^^^^^^^^^^^^ 43 | 44 | The **Windows 9x family** will automatically detect Plug and Play IDE controllers on boot. Non-Plug and Play controllers will be detected during installation :ref:`only if the BIOS supports them `. Follow these steps to enable a non-Plug and Play controller on an already-installed system: 45 | 46 | 1. Go to the *Add New Hardware* control panel. 47 | 2. Add a *Standard IDE/ESDI Hard Disk Controller* from the *Hard disk controllers* category. 48 | 3. Don't restart the system when asked to. 49 | 4. Go to the *Device Manager* tab of the *System* control panel. 50 | 5. Select the newly-added *Standard IDE/ESDI Hard Disk Controller* device from the *Hard disk controllers* category and click *Properties*. 51 | 6. Go to the *Resources* tab. 52 | 7. Select *Basic configuration 4* in the *Settings based on* box. 53 | 8. Change the resource settings to match the I/O ports on the :ref:`table above ` and the configured IRQ. The first *Input/Output Range* range corresponds to the **main** I/O port, the second one corresponds to the **status** I/O port, and *Interrupt Request* corresponds to the IRQ. 54 | 55 | * The status I/O port range is off by 6. Select 03E8 for the tertiary channel or 0368 for the quaternary channel. 56 | * The screenshot below shows an example configuration for the tertiary channel. 57 | 58 | 9. If both the tertiary and quaternary channels are enabled, repeat the steps above to enable the other controller. 59 | 60 | .. image:: images/ideterqua_win98.png 61 | :align: center 62 | 63 | Windows NT, 2000 and XP 64 | ^^^^^^^^^^^^^^^^^^^^^^^ 65 | 66 | **Windows 2000 and XP** will automatically detect Plug and Play IDE controllers on boot. Additionally, **Windows NT 3.5, 4.0, 2000 and XP** will automatically detect non-Plug and Play controllers during installation, regardless of BIOS support; however, this auto-detection of non-PnP controllers does not work on most machines with **Award BIOS**. 67 | 68 | .. note:: If you install the system to a hard disk on one of the additional controllers, it will not be bootable unless :ref:`the BIOS supports booting from these controllers `. 69 | 70 | On **Windows 2000 only**, non-Plug and Play controllers can be enabled on an already-installed system through *Add New Hardware* similarly to :ref:`Windows 9x as shown above `. The resource parameters cannot be changed, and therefore, only the :ref:`default IRQs for each controller ` are supported. *Basic configuration 0002* corresponds to the **tertiary** channel, while *Basic configuration 0003* corresponds to the **quaternary** channel. 71 | 72 | Windows Vista and 7 73 | ^^^^^^^^^^^^^^^^^^^ 74 | 75 | The **Windows NT 6 family** does not support legacy (ISA or VLB) IDE controllers, and therefore cannot use the additional channels as currently emulated by 86Box. 76 | 77 | Linux 78 | ^^^^^ 79 | 80 | There are different steps for enabling additional IDE controllers on Linux, depending on which IDE driver stack is used by your distribution's kernel. 81 | 82 | Modules can be loaded at any time with the ``modprobe`` command, or loaded on boot by adding the module's name (and parameters if required) to a file in ``/etc/modules-load.d`` on newer systemd-based distributions, or the ``/etc/modules`` file on older distributions. 83 | 84 | * **Legacy IDE** (typically kernels **older than 2.6.19**): 85 | 86 | * Load the ``ide-pnp`` module to enable Plug and Play controllers. 87 | * Non-Plug and Play controllers require editing the kernel command line on your bootloader to add each controller's I/O ports and IRQ: 88 | 89 | * **Tertiary:** ``ide2=0x1e8,0x3ee,11`` (assuming IRQ 11) 90 | * **Quaternary:** ``ide3=0x168,0x36e,10`` (assuming IRQ 10) 91 | 92 | * **libATA** (typically kernels **2.6.19 and above**): 93 | 94 | * Load the ``pata_isapnp`` module to enable Plug and Play controllers. 95 | * Load the ``pata_legacy`` module with the ``probe_all=1`` parameter to automatically detect and enable non-Plug and Play controllers. Only the :ref:`default IRQs for each controller ` are supported. 96 | 97 | .. note:: Some distributions may automatically detect additional IDE controllers; however, that is very rarely the case. 98 | -------------------------------------------------------------------------------- /hardware/images/ideterqua_win98.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/hardware/images/ideterqua_win98.png -------------------------------------------------------------------------------- /hardware/images/isabugger.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/hardware/images/isabugger.png -------------------------------------------------------------------------------- /hardware/isabugger.rst: -------------------------------------------------------------------------------- 1 | ISABugger 2 | ========= 3 | 4 | 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 `. 5 | 6 | These displays and LEDs are displayed on the :ref:`status bar ` as described in the diagram below: 7 | 8 | .. image:: images/isabugger.png 9 | :align: center 10 | 11 | Background 12 | ---------- 13 | 14 | From ``src/device/bugger.c``: 15 | 16 | .. code-block:: none 17 | 18 | Implementation of the ISA Bus (de)Bugger expansion card 19 | sold as a DIY kit in the late 1980's in The Netherlands. 20 | This card was a assemble-yourself 8bit ISA addon card for 21 | PC and AT systems that had several tools to aid in low- 22 | level debugging (mostly for faulty BIOSes, bootloaders 23 | and system kernels...) 24 | 25 | The standard version had a total of 16 LEDs (8 RED, plus 26 | 8 GREEN), two 7-segment displays and one 8-position DIP 27 | switch block on board for use as debugging tools. 28 | 29 | The "Plus" version, added an extra 2 7-segment displays, 30 | as well as a very simple RS-232 serial interface that 31 | could be used as a mini-console terminal. 32 | 33 | Registers 34 | --------- 35 | 36 | The ISABugger's control registers can be accessed through the following operations on I/O ports ``0x7a`` and ``0x7b``: 37 | 38 | * **Writing:** write the register's index to port ``0x7a``, then write the value to port ``0x7b``. 39 | * **Reading:** write the register's index to port ``0x7a``, then read the value from port ``0x7b``. 40 | * **Index reading:** the last register index written to port ``0x7a`` can be read back from the same port. The most significant bit is always set, as an indicator that the ISABugger is enabled. 41 | 42 | .. 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. 43 | 44 | Register reference 45 | ^^^^^^^^^^^^^^^^^^ 46 | 47 | .. rubric:: Index ``0x00`` - Red LEDs (write-only) 48 | .. rubric:: Index ``0x01`` - Green LEDs (write-only) 49 | 50 | 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**). 51 | 52 | .. rubric:: Index ``0x02`` - Right display (write-only) 53 | .. rubric:: Index ``0x04`` - Left display (write-only) 54 | 55 | Each display shows a hexadecimal representation of the 8-bit value written to its register. 56 | 57 | .. rubric:: Index ``0x20`` - Serial port data (not implemented) (read/write) 58 | .. rubric:: Index ``0x40`` - Serial port configuration (not implemented) (read/write) 59 | 60 | 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. 61 | 62 | .. rubric:: Index ``0x80`` - Initialize (not implemented) (write-only) 63 | 64 | This register has **no effect** on 86Box, as the emulated ISABugger is always enabled and ready. 65 | 66 | .. rubric:: Index ``0xff`` - Reset (special) 67 | 68 | Writing register index ``0xff`` to port ``0x7a`` will immediately reset all registers to their startup value, clearing all displays and LED banks. 69 | 70 | This is a **special register** which cannot be read or written; writing to port ``0x7b`` immediately after a reset will result in the value being sent to the default register index of ``0x00``, which corresponds to the red LEDs. 71 | -------------------------------------------------------------------------------- /hardware/keyboard.rst: -------------------------------------------------------------------------------- 1 | Keyboard 2 | ======== 3 | 4 | This page outlines keyboard behavior specific to different host operating systems, real keyboards and emulated machines. 5 | 6 | Host systems 7 | ------------ 8 | 9 | Windows 10 | ^^^^^^^ 11 | 12 | * Not all multimedia function keys can be passed through to the emulated machine due to a Windows limitation. 13 | * Multimedia key passthrough can be disabled entirely through the *Inhibit multimedia keys on Windows* option on the :ref:`Preferences window `. 14 | * System-wide key remapping through the **Scancode Map** registry key (as performed by applications such as SharpKeys) is fully supported. 15 | 16 | macOS 17 | ^^^^^ 18 | 19 | * Apple keyboards with **European or other ISO layouts** may have *the key below Esc* and *the key to the right of Left Shift* switch places in the emulated machine, due to a hardware quirk in many of those keyboards (both internal and external) and a limitation in the way macOS corrects it. 20 | * The **Num =** key is only usable in operating systems which recognize that key on Microsoft PS/2 multimedia keyboards. 21 | * Mac special keys are mapped to their PC equivalents where possible: 22 | 23 | .. list-table:: 24 | :header-rows: 1 25 | :widths: 1 999 26 | 27 | * - Emulated key 28 | - Host key 29 | 30 | * - Windows 31 | - Command 32 | 33 | * - Alt 34 | - Option 35 | 36 | * - Print Screen 37 | - F13 38 | 39 | * - Scroll Lock 40 | - F14 41 | 42 | * - Pause 43 | - F15 44 | 45 | * - Insert 46 | - Command + Fn + Delete (MacBook and tenkeyless keyboards) 47 | 48 | Command + Forward Delete (full size keyboards) 49 | 50 | * - Num Lock 51 | - Clear 52 | 53 | Linux 54 | ^^^^^ 55 | 56 | * The `xkbcommon `_ library is used to accurately map physical keys to the emulated keyboard on both X11 and Wayland. When compiling 86Box from source, make sure the development files for ``libxkbcommon`` and ``libxkbcommon-x11`` are installed, as this is an optional build component. 57 | 58 | 59 | Special keys 60 | ------------ 61 | 62 | Some machines provide additional function or otherwise special keys on top of the standard PC layout. Those keys are mapped to ones present on modern keyboards within reason. 63 | 64 | Olivetti 65 | ^^^^^^^^ 66 | 67 | The Olivetti M series special keys are mapped as such: 68 | 69 | .. list-table:: 70 | :header-rows: 1 71 | :widths: 1 999 72 | 73 | * - Emulated key 74 | - Host key 75 | 76 | * - CLEAR 77 | - Page Up 78 | 79 | * - BREAK 80 | - Page Down 81 | 82 | * - SCR PRT 83 | - Print Screen 84 | 85 | * - HELP 86 | - Menu 87 | 88 | * - 00 89 | - Left Windows 90 | 91 | * - F13 92 | - Insert 93 | 94 | * - F14 95 | - Home 96 | 97 | * - F15 98 | - Del 99 | 100 | * - F16 101 | - End 102 | 103 | * - F17 104 | - Right Alt 105 | 106 | * - F18 107 | - Right Win 108 | 109 | 110 | Toshiba 111 | ^^^^^^^ 112 | 113 | The Toshiba T1000 series function keys can be accessed by holding Right Alt or Right Ctrl: 114 | 115 | .. list-table:: 116 | :header-rows: 1 117 | 118 | * - Function 119 | - Right Alt/Ctrl + 120 | 121 | * - Show/hide numeric keypad overlay 122 | - Num Lock 123 | 124 | * - Change internal display font 125 | - Right 126 | 127 | * - Use internal display 128 | - Home 129 | 130 | * - Use external display 131 | - End 132 | 133 | * - Turbo mode on (T1200) 134 | - Page Up 135 | 136 | * - Turbo mode off (T1200) 137 | - Page Down 138 | 139 | * - Show/hide pop-up window (T1200) 140 | - Print Screen 141 | -------------------------------------------------------------------------------- /hardware/machinespecific.rst: -------------------------------------------------------------------------------- 1 | Machine-specific notes 2 | ====================== 3 | 4 | This page contains important notes related to specific machine models emulated by 86Box. 5 | 6 | ---- 7 | 8 | 8088 9 | ---- 10 | 11 | .. _ibmpc: 12 | .. rubric:: IBM PC 13 | 14 | * The 1981 and 1982 variants correspond to the `earlier 16KB-64KB and later 64KB-256KB revisions of the motherboard `_, with different BIOS versions and memory size limits. 15 | 16 | * Those limits apply to on-board RAM; more can be added through :ref:`ISA memory expansion ` cards. 17 | 18 | .. rubric:: IBM PCjr 19 | 20 | * Some applications may shift the display slightly to one side due to unconventional use of the PCjr video hardware. Unchecking the **Apply overscan deltas** option accessible through the internal video's :ref:`Configure button ` can help bring the display back into position. 21 | * Hard disks are not supported, as a PCjr-compatible hard disk controller is not emulated by 86Box. 22 | 23 | .. _ibmxt: 24 | .. rubric:: IBM XT 25 | 26 | * The 1982 and 1986 variants correspond to the `earlier 64-256KB and later 256-640KB revisions of the motherboard `_, with different BIOS versions and memory size limits. 27 | 28 | * Those limits apply to on-board RAM; more can be added through :ref:`ISA memory expansion ` cards. 29 | 30 | 80286 31 | ----- 32 | 33 | .. _ibmat: 34 | .. rubric:: IBM AT 35 | 36 | * On-board RAM is limited to 512 KB; more can be added through :ref:`ISA memory expansion ` cards. 37 | * 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. 38 | 39 | .. rubric:: IBM XT Model 286 40 | 41 | * On-board RAM is limited to 640 KB; more can be added through :ref:`ISA memory expansion ` cards. 42 | 43 | .. rubric:: AMI IBM AT 44 | 45 | See: :ref:`ibmat` 46 | 47 | .. rubric:: Phoenix IBM AT 48 | 49 | See: :ref:`ibmat` 50 | 51 | .. rubric:: Quadtel IBM AT 52 | 53 | See: :ref:`ibmat` 54 | 55 | .. rubric:: GRiD GRiDcase 1520 56 | 57 | * The BIOS is locked to specific Conner IDE hard disk models. Any hard disks must be set to the **Conner CP3024**, **CP3044** or **CP3104** :ref:`model profiles `. 58 | * The Yamaha V6366 video chip is not emulated by 86Box. An **IBM CGA** set to amber monochrome mode (through the :ref:`Configure button `) is recommended as an approximation. 59 | 60 | i386SX 61 | ------ 62 | 63 | .. rubric:: Amstrad MegaPC 64 | 65 | * The BIOS does not configure itself on first boot or after clearing CMOS; the machine will not work properly until an automatic configuration is performed by pressing **F9** on the BIOS setup's main *Setup* menu, then saving with **F10** and exiting with **Esc**. 66 | 67 | i486 68 | ---- 69 | 70 | .. rubric:: IBM Aptiva 510/710/Vision 71 | 72 | * The BIOS setup utility is only available in Japanese. For English, use the otherwise identical **IBM PC 330 (type 6573)**. 73 | 74 | .. rubric:: Zida Tomato 4DP 75 | 76 | * Floppy drive support is completely disabled by default. It can be enabled through the *Onboard FDD Controller* option of the *Chipset Features Setup* menu on the BIOS setup; the floppy drives themselves must also be configured in the *Standard CMOS Setup* menu. 77 | 78 | Socket 7 79 | -------- 80 | 81 | .. rubric:: MSI MS-5119 82 | 83 | * 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. 84 | 85 | .. _p65up5: 86 | .. rubric:: ASUS P/I-P65UP5 (C-P55T2D) 87 | 88 | * Modular motherboard, consisting of a **P/I-P65UP5** baseboard and one of the following CPU cards: 89 | 90 | * **C-P55T2D:** Socket 7 with Intel 430HX northbridge; 91 | * **C-P6ND:** Socket 8 with Intel 440FX northbridge; 92 | * **C-PKND:** Slot 1 with Intel 440FX northbridge. 93 | 94 | * While the northbridge depends on the selected CPU card, the southbridge always remains the Intel PIIX3, as it is located on the baseboard. 95 | * The real CPU cards support dual CPUs. As 86Box does not emulate multiprocessing, only a single CPU will be present. 96 | * Due to a lack of I/O APIC emulation at the moment, 86Box will patch the MultiProcessor Specification tables out of RAM during boot, so that operating systems will not hang or exhibit other erratic behavior due to the missing I/O APIC. 97 | 98 | .. _ma23c: 99 | .. rubric:: NEC Mate NX MA23C 100 | 101 | * Accessing the BIOS setup utility takes an additional step. Press **F2** during the NEC logo screen and some Japanese text will appear; once a different line of text appears, press the **right arrow** key to enter the setup utility. 102 | * The first setup option below the date and time can be used to change the BIOS language to English. 103 | 104 | Socket 8 105 | -------- 106 | 107 | .. rubric:: ASUS P/I-P65UP5 (C-P6ND) 108 | 109 | See: :ref:`p65up5` 110 | 111 | Slot 1 112 | ------ 113 | 114 | .. rubric:: ASUS P/I-P65UP5 (C-PKND) 115 | 116 | See: :ref:`p65up5` 117 | 118 | .. _atc6310bxii: 119 | .. rubric:: A-Trend ATC6310BXII 120 | 121 | * Equipped with the obscure SMSC Victory66 southbridge instead of the regular Intel PIIX4E. 122 | 123 | * The Victory66 has faster IDE - up to Ultra ATA/66 as opposed to the PIIX4E's Ultra ATA/33 - and a different USB controller. 124 | * Drivers for Windows 95, 98, Me and 2000 are available `here `_. Windows XP, Vista and 7 include drivers out of the box. 125 | 126 | .. rubric:: NEC Mate NX MA30D/23D 127 | 128 | See: :ref:`ma23c` 129 | 130 | Slot 1/2 131 | -------- 132 | 133 | .. rubric:: Freeway FW-6400GX 134 | 135 | * The maximum amount of RAM is limited to 2032 MB due to a BIOS bug with 2048 MB. 136 | * 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. 137 | * Once enabled, ACPI :ref:`does not work correctly ` if a non-Intel CPU is selected. 138 | 139 | Slot 2 140 | ------ 141 | 142 | .. rubric:: Gigabyte GA-6GXU 143 | 144 | * The BIOS display will corrupt itself during the memory test if the maximum of 2048 MB RAM is selected. This is a visual glitch which does not otherwise negatively impact the machine. 145 | 146 | Socket 370 147 | ---------- 148 | 149 | .. rubric:: A-Trend ATC7020BXII 150 | 151 | See: :ref:`atc6310bxii` 152 | 153 | .. rubric:: AEWIN AW-O671R 154 | 155 | * Equipped with dual Winbond W83977EF Super I/O chips driving four serial (COM1-COM4) and two parallel (LPT1-LPT2) ports. 156 | 157 | * The I/O ports and IRQs used by all these ports can be configured in the BIOS setup. 158 | 159 | * ACPI is disabled by default, unlike other machines with Award v6.00PG BIOS. It can be enabled through the *ACPI function* option of the *Power Management Setup* menu on the BIOS setup. 160 | 161 | Miscellaneous 162 | ------------- 163 | 164 | .. rubric:: Microsoft Virtual PC 2007 165 | 166 | * This machine loads the American Megatrends BIOS from Virtual PC 2007 into 86Box's emulation. It does not use the virtualization engine or any other components from Virtual PC. 167 | * Virtual PC's special 8 MB video card, WDM sound card and Guest Additions are not emulated by 86Box. 168 | 169 | ---- 170 | 171 | Footnotes 172 | --------- 173 | 174 | .. _brokenacpi: 175 | .. rubric:: Broken ACPI 176 | 177 | Some machines may have faulty or otherwise incomplete `Advanced Configuration and Power Interface `_ implementations in their BIOSes, symptoms of which include: 178 | 179 | * Windows 2000 and higher will install the "Standard PC" HAL, which does not enable ACPI features such as soft power off and sleep mode; 180 | * Booting an existing Windows installation with the ACPI HAL will result in a STOP 0x000000A5 blue screen; 181 | * Booting Windows Vista or 7 (which require ACPI) will also result in a STOP 0x000000A5 blue screen, or a Windows Boot Manager 0xc0000225 error. 182 | 183 | There is no solution to this issue, as none of the currently emulated machines with broken ACPI ever received a BIOS update to fix it. 184 | -------------------------------------------------------------------------------- /hardware/network.rst: -------------------------------------------------------------------------------- 1 | Networking 2 | ========== 3 | 4 | 86Box supports different connection modes for the :doc:`emulated network cards <../settings/network>`. The specific details on these connection modes and network emulation as a whole are outlined on this page. 5 | 6 | Null Driver 7 | ----------- 8 | 9 | Default mode. The selected network card will be available to the emulated machine, but any packets sent through it will be dropped. 10 | 11 | In this mode, the network card will default to a disconnected cable on startup; if the cable is connected through the :ref:`status bar ` or :ref:`Media menu `, cards with link state detection support will report a connection, but packets will still be dropped. 12 | 13 | SLiRP 14 | ----- 15 | 16 | SLiRP creates a private network with a virtual router, allowing the emulated machine to reach the host, its network and the Internet; on the other hand, the host and other devices on its network cannot reach the emulated machine, unless :ref:`port forwarding ` is configured. This is similar to the **NAT** mode on other emulators and virtualizers. 17 | 18 | The virtual router provides automatic IP configuration to the emulated machine through DHCP. If that is not an option, use the following static IP settings, replacing *x* with 2, 3, 4 or 5 for the first, second, third or fourth network card to use SLiRP respectively: 19 | 20 | * **IP address:** 10.0.\ *x*\ .15 21 | * **Subnet mask:** 255.255.255.0 22 | * **Default gateway:** 10.0.\ *x*\ .2 23 | * **DNS server:** 10.0.\ *x*\ .3 24 | 25 | The host can be reached through IP address 10.0.\ *x*\ .2, while other devices on the host's network can be reached through their normal IP addresses. 26 | 27 | .. note:: SLiRP is only capable of routing TCP and UDP traffic, with limited ICMP ping support. Other protocols such as IPX and NetBEUI can only be used with :ref:`hardware/network:PCap` or :ref:`hardware/network:VDE` networking. 28 | 29 | PCap 30 | ---- 31 | 32 | PCap connects directly to one of the host's network adapters. The emulated machine must be configured as if it were a real machine on your network. This is similar to the **Bridge** mode on other emulators and virtualizers. 33 | 34 | On Windows hosts, this mode requires `Npcap `_ to be installed with **WinPcap API-compatible Mode enabled** (or use another WinPcap-compatible driver), or the correct permissions to be set for accessing ``pcap`` on Linux or ``bpf`` on macOS hosts. **Only wired Ethernet network connections** are compatible; Wi-Fi and other connections will not work at all, as they do not allow PCap to listen for packets bound to the emulated card's MAC address. 35 | 36 | Private PCap network 37 | ^^^^^^^^^^^^^^^^^^^^ 38 | 39 | If you have an incompatible network connection on your host system (such as Wi-Fi), or if you wish to connect the emulated machine to the host without also connecting it to your network, a private network can be created with PCap in one of two ways: 40 | 41 | * Install and configure the *Microsoft KM-TEST Loopback Adapter* included with Windows. 42 | 43 | * Guides on how to install this adapter are available online. 44 | * The adapter alone only provides a direct connection to the host, with no DHCP server, therefore requiring manual IP configuration on both the host and the emulated machine. 45 | * Windows' *Internet Connection Sharing* feature can be used to connect the emulated machine to the host's network and the Internet, with DHCP for automatic IP configuration, similarly to SLiRP but with the added benefit that the host can reach the emulated machine without port forwarding. 46 | 47 | * Port forwarding can be performed through Internet Connection Sharing's *Settings*. 48 | 49 | * If VMware is installed, use one of the VMnet adapters included with it. 50 | 51 | * *VMnet1* (Host-only) connects to the host only. 52 | * *VMnet8* (NAT) connects to the host, its network and the Internet. 53 | 54 | * Port forwarding can be performed through the Virtual Network Editor's *NAT Settings*. 55 | 56 | VDE 57 | --- 58 | 59 | `Virtual Distributed Ethernet `_ is a virtual Ethernet switch system for connecting different applications such as 86Box to each other. See `VDE Basic Networking `_ for a brief overview. 60 | 61 | .. note:: VDE is only available on **Linux** and **macOS** hosts. 62 | 63 | One of VDE's core concepts is the *plug*. 86Box allows for *plug*\ ging an emulated machine into a virtual switch created by VDE; this virtual layer 2 switch is capable of carrying any Ethernet-based protocols such as IP and IPX. 64 | 65 | Installing VDE tools 66 | ^^^^^^^^^^^^^^^^^^^^ 67 | 68 | The VDE tools are required to create the virtual switch that 86Box attaches to with a virtual cable. 69 | 70 | Linux 71 | """"" 72 | 73 | On Debian, Ubuntu and derivatives, VDE and some of its associated commands are split into different packages. Install the libraries and their associated tools: 74 | 75 | .. code-block:: shell 76 | 77 | apt install libvdeplug2 vde-switch vde2 78 | 79 | .. note:: Other distributions should have similar package names. 80 | 81 | macOS 82 | """"" 83 | 84 | VDE is available through Homebrew or MacPorts. 85 | 86 | .. code-block:: shell 87 | 88 | brew install vde 89 | 90 | .. code-block:: shell 91 | 92 | port install vde2 93 | 94 | Creating the virtual switch 95 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ 96 | 97 | Before connecting 86Box, a virtual switch must be created with the ``vde_switch`` tool. 98 | 99 | .. code-block:: shell 100 | 101 | vde_switch --numports 8 --mgmt /tmp/vde.mgmt -s /tmp/vde.ctl 102 | 103 | This command: 104 | 105 | * Creates the *management* socket at ``/tmp/vde.mgmt`` 106 | * Creates the *control* socket at ``/tmp/vde.ctl`` 107 | * Sets the number of switch ports to 8 (default is 32) 108 | 109 | Adding ``--daemon`` to the command will run ``vde_switch`` in the background. 110 | 111 | Note the ``/tmp/vde.ctl`` path for the control socket, which is what should be provided in the :ref:`network settings `. 112 | 113 | .. note:: You can adjust the file paths or permissions as necessary. Refer to ``vde_switch -h`` for more information on available options. 114 | 115 | Configuring 86Box for VDE 116 | ^^^^^^^^^^^^^^^^^^^^^^^^^ 117 | 118 | Go to the emulated machine's :doc:`network settings <../settings/network>` and select *VDE* as the mode for the emulated network card. Enter the *control* socket path, which is ``/tmp/vde.ctl`` for the example above, in the *VDE Socket* box. 119 | 120 | Once these settings are saved, the machine should automatically connect to the VDE switch. Check the :ref:`status bar ` or :ref:`Media menu ` to make sure the emulated network cable is actually connected. 121 | 122 | VDE switch status 123 | ^^^^^^^^^^^^^^^^^ 124 | 125 | The ``vdeterm`` command can be used to view the status of the virtual switch. It requires the path to the *management* socket (instead of the *control* socket) created alongside the switch; the command would be ``vdeterm /tmp/vde.mgmt`` for the example above. 126 | 127 | Once in the command line, enter ``help`` to view a list of available commands. One helpful command is ``port/allprint`` which displays a list of all virtual switch ports and the processes attached to them: 128 | 129 | .. code-block:: 130 | 131 | vde[/tmp/vde.mgmt]: port/allprint 132 | 133 | Port 0001 untagged_vlan=0000 ACTIVE - Unnamed Allocatable 134 | Current User: myusername Access Control: (User: NONE - Group: NONE) 135 | -- endpoint ID 0003 module unix prog : 86Box virtual card user=myusername PID=12345 136 | Success 137 | 138 | In addition to ``vdeterm``, the command line interface can be accessed through ``vde_switch`` if it was started without the ``--daemon`` option, by pressing Enter on its terminal. 139 | 140 | Other VDE features 141 | ^^^^^^^^^^^^^^^^^^ 142 | 143 | This guide only covers the basics of VDE. It provides many more useful features such as: 144 | 145 | * Connecting virtual switches **across host machines** with ``vde_cryptcab`` 146 | * Bridging virtual switches with **network interfaces** to provide access to the Internet and other networks 147 | * Connecting to **other emulators and virtualizers** with VDE support such as QEMU and VirtualBox 148 | * Creating **VLANs and access control policies** which can be assigned to switch ports 149 | 150 | Modem 151 | ----- 152 | 153 | The emulated modem can **dial-out** to Telnet servers as a client, receive **dial-in** calls as a server, or connect to a network through SLIP **dial-up**. 154 | 155 | .. important:: The :ref:`hardware/network:Telnet client` and :ref:`hardware/network:SLIP` modes cannot understand **country and area codes**, which are enabled by default on Windows. Check your dialing settings if you always get *no answer* or *no carrier*. 156 | 157 | The *Configure* button next to the :ref:`network card selector ` provides these settings for a modem: 158 | 159 | * **Serial Port:** port to attach the modem. When using other serial devices such as a :ref:`mouse ` or :ref:`serial passthrough `, make sure to select a port that is not used. 160 | * **Baud Rate:** bit rate for communicating with the modem. This has an impact on the reported and actual transfer speeds. 161 | * **TCP/IP listening port:** TCP port number used for the :ref:`hardware/network:Telnet server` to receive dial-in connections, or ``0`` to disable dial-in. 162 | * **Phonebook File:** text file containing a list of phone numbers and the addresses they should connect to. Format is one entry per line (up to 200 entries), with the phone number, followed by a space or tab, followed by the address to connect to. 163 | * **Telnet emulation:** handle Telnet protocol sequences instead of passing them through the modem. If this option is off, then a raw connection is established. 164 | 165 | .. note:: Telnet emulation must be **on** for connecting to some Telnet servers which require option negotiation, and **off** for connecting two 86Box machines or other binary applications. 166 | 167 | Telnet client 168 | ^^^^^^^^^^^^^ 169 | 170 | Dial the ``address`` (defaults to port 23) or ``address:port`` of a Telnet server as a phone number to connect to it through the modem. Both IP addresses and DNS names are accepted. 171 | 172 | For dialer software which does not support entering ``.`` or ``:`` as part of a phone number, an alternative option is specifying a zero-padded IP optionally followed by a port number, such as ``010176001086`` for ``10.176.1.86`` on the default port 23, or ``0101760010864321`` for ``10.176.1.86:4321``. 173 | 174 | Telnet server 175 | ^^^^^^^^^^^^^ 176 | 177 | By setting the modem's **TCP/IP listening port** option, a **dial-in server** is started on that port, allowing a Telnet client or another application to dial into the emulated machine by connecting to the host on the specified port number. The modem rings as soon as a TCP connection is received by the listening server; the server will refuse connections if an incoming or outgoing call is already active, as call waiting is not emulated. 178 | 179 | For games and other applications that support dial-in, a connection **between 86Box machines** can be established with this mode, by configuring the first machine to listen as a server, and having the second machine dial into the first one's IP and port. 180 | 181 | SLIP 182 | ^^^^ 183 | 184 | Dial number ``0.0.0.0`` or ``000000000000`` (twelve zeros) to establish a **Serial Line Internet Protocol (SLIP)** dial-up network connection. SLiRP is the only supported network mode when using a modem; other modes are ignored. 185 | 186 | .. important:: This is not the standard PPP connection mode typically used by dial-up providers around the world; therefore, dialer software that is compatible with and configured for SLIP must be used. 187 | 188 | Example configuration for Windows 98 189 | """""""""""""""""""""""""""""""""""" 190 | 191 | 1. Open the *Connect to the Internet* desktop shortcut. Depending on your Windows region, this opens either the MSN setup wizard or the Internet Connection Wizard, which will in turn open the modem setup wizard to add a modem. 192 | 2. Check *Don't detect my modem; I will select it from a list* and click *Next*. 193 | 3. Select any of the standard modem types and click *Next*. The speed does not matter, as the configured baud rate is automatically used. 194 | 4. Select the serial port to which the modem is connected (COM1 by default) and click *Next*. 195 | 5. Wait for the modem to install and click *Finish*. 196 | 6. If you're on the MSN setup wizard, click *Lan/Manual* to switch to the proper Internet Connection Wizard. 197 | 7. Select *Connect using my phone line* and click *Next*. 198 | 8. Enter ``0.0.0.0`` as the phone number and **uncheck** *Dial using the area code and country code*. 199 | 9. Click *Advanced...* and perform these changes: 200 | 201 | * On the *Connection* tab, set the **connection type** to *SLIP (Serial Line Internet Protocol)*. 202 | * On the *Addresses* tab, set the IP and DNS addresses **manually** according to :ref:`the SLiRP rules above `. For the first SLiRP instance, these are 10.0.2.15 for IP and 10.0.2.3 for DNS. 203 | * Click *OK* then *Next*. 204 | 205 | 10. Leave the username and password **blank** and click *Next* then *Yes* on both warnings. 206 | 11. Set the connection name (or leave the default alone) and click *Next*. 207 | 12. Skip setting up an e-mail account and click *Next* then *Finish*. 208 | 209 | To connect through dial-up, open Internet Explorer and click *Connect* when prompted. When the *Terminal Screen* shows up, click *Continue* and the connection will be established. 210 | 211 | Advanced networking features 212 | ---------------------------- 213 | 214 | The following advanced features can be accessed by directly editing the emulated machine's configuration file, which is ``86box.cfg`` by default. 215 | 216 | SLiRP port forwarding 217 | ^^^^^^^^^^^^^^^^^^^^^ 218 | 219 | 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. 220 | 221 | 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: 222 | 223 | * ``X_protocol``: Port type: ``tcp`` or ``udp`` (default: ``tcp``) 224 | * ``X_external``: Port number on the host (default: same port number as ``X_internal``) 225 | * ``X_internal``: Port number on the emulated machine (default: same port number as ``X_external``) 226 | 227 | 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. 228 | 229 | .. 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. 230 | 231 | .. container:: toggle-always-show 232 | 233 | .. container:: toggle-header 234 | 235 | Example: forward host TCP port 8080 to emulated machine port 80, and host UDP port 5555 to emulated machine port 5555 236 | 237 | .. code-block:: none 238 | 239 | [SLiRP Port Forwarding #1] 240 | 0_external = 8080 241 | 0_internal = 80 242 | 1_protocol = udp 243 | 1_external = 5555 244 | -------------------------------------------------------------------------------- /icons.sh: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | 3 | # Check for repository path. 4 | if [ -z "$1" ] 5 | then 6 | echo Specify 86Box repository path. ImageMagick is required. 7 | exit 1 8 | fi 9 | 10 | # Determine the ImageMagick executable. 11 | magick=magick 12 | $magick >/dev/null 2>&1 || magick=magick.exe 13 | 14 | # Convert icons to PNG. 15 | for i in "$1/src/qt/icons/"*.ico 16 | do 17 | $magick convert "$i" "usage/images/$(basename $i | sed -e 's/.ico$//').png" 18 | done 19 | 20 | # Remove unnecessary icons. 21 | cd usage/images 22 | rm -f 86Box-* *active* *disabled* *mute* *-1.png *-2.png 23 | 24 | # Get small and big icons. 25 | for i in *-0.png 26 | do 27 | mv "$i" "$(echo $i | sed -e 's/-0/_small/')" 28 | done 29 | for i in *-3.png 30 | do 31 | mv "$i" "$(echo $i | sed -e 's/-3//')" 32 | done 33 | for i in *-4.png 34 | do 35 | mv "$i" "$(echo $i | sed -e 's/-4//')" 36 | done 37 | 38 | # Create include.rst entries. 39 | for i in *.png 40 | do 41 | echo '.. |'$(echo $i | sed -e 's/.png//')'| image:: /usage/images/'$i 42 | done 43 | -------------------------------------------------------------------------------- /include.rst: -------------------------------------------------------------------------------- 1 | .. |br| raw:: html 2 | 3 |
  4 | .. |vel| unicode:: 0x22EE 5 | :trim: 6 | 7 | .. |acpi_shutdown| image:: /usage/images/acpi_shutdown.png 8 | .. |acpi_shutdown_small| image:: /usage/images/acpi_shutdown_small.png 9 | .. |caps_lock_off| image:: /usage/images/caps_lock_off.png 10 | .. |caps_lock_off_small| image:: /usage/images/caps_lock_off_small.png 11 | .. |caps_lock_on| image:: /usage/images/caps_lock_on.png 12 | .. |caps_lock_on_small| image:: /usage/images/caps_lock_on_small.png 13 | .. |cartridge| image:: /usage/images/cartridge.png 14 | .. |cartridge_small| image:: /usage/images/cartridge_small.png 15 | .. |cassette| image:: /usage/images/cassette.png 16 | .. |cassette_small| image:: /usage/images/cassette_small.png 17 | .. |cdrom| image:: /usage/images/cdrom.png 18 | .. |cdrom_folder| image:: /usage/images/cdrom_folder.png 19 | .. |cdrom_folder_small| image:: /usage/images/cdrom_folder_small.png 20 | .. |cdrom_host| image:: /usage/images/cdrom_host.png 21 | .. |cdrom_host_small| image:: /usage/images/cdrom_host_small.png 22 | .. |cdrom_image| image:: /usage/images/cdrom_image.png 23 | .. |cdrom_image_small| image:: /usage/images/cdrom_image_small.png 24 | .. |cdrom_small| image:: /usage/images/cdrom_small.png 25 | .. |display| image:: /usage/images/display.png 26 | .. |display_small| image:: /usage/images/display_small.png 27 | .. |floppy_35| image:: /usage/images/floppy_35.png 28 | .. |floppy_35_small| image:: /usage/images/floppy_35_small.png 29 | .. |floppy_525| image:: /usage/images/floppy_525.png 30 | .. |floppy_525_small| image:: /usage/images/floppy_525_small.png 31 | .. |floppy_and_cdrom_drives| image:: /usage/images/floppy_and_cdrom_drives.png 32 | .. |floppy_and_cdrom_drives_small| image:: /usage/images/floppy_and_cdrom_drives_small.png 33 | .. |hard_disk| image:: /usage/images/hard_disk.png 34 | .. |hard_disk_small| image:: /usage/images/hard_disk_small.png 35 | .. |hard_reset| image:: /usage/images/hard_reset.png 36 | .. |hard_reset_small| image:: /usage/images/hard_reset_small.png 37 | .. |input_devices| image:: /usage/images/input_devices.png 38 | .. |input_devices_small| image:: /usage/images/input_devices_small.png 39 | .. |kana_lock_off| image:: /usage/images/kana_lock_off.png 40 | .. |kana_lock_off_small| image:: /usage/images/kana_lock_off_small.png 41 | .. |kana_lock_on| image:: /usage/images/kana_lock_on.png 42 | .. |kana_lock_on_small| image:: /usage/images/kana_lock_on_small.png 43 | .. |machine| image:: /usage/images/machine.png 44 | .. |machine_small| image:: /usage/images/machine_small.png 45 | .. |mo| image:: /usage/images/mo.png 46 | .. |mo_small| image:: /usage/images/mo_small.png 47 | .. |network| image:: /usage/images/network.png 48 | .. |network_small| image:: /usage/images/network_small.png 49 | .. |num_lock_off| image:: /usage/images/num_lock_off.png 50 | .. |num_lock_off_small| image:: /usage/images/num_lock_off_small.png 51 | .. |num_lock_on| image:: /usage/images/num_lock_on.png 52 | .. |num_lock_on_small| image:: /usage/images/num_lock_on_small.png 53 | .. |other_peripherals| image:: /usage/images/other_peripherals.png 54 | .. |other_peripherals_small| image:: /usage/images/other_peripherals_small.png 55 | .. |other_removable_devices| image:: /usage/images/other_removable_devices.png 56 | .. |other_removable_devices_small| image:: /usage/images/other_removable_devices_small.png 57 | .. |pause| image:: /usage/images/pause.png 58 | .. |pause_small| image:: /usage/images/pause_small.png 59 | .. |ports| image:: /usage/images/ports.png 60 | .. |ports_small| image:: /usage/images/ports_small.png 61 | .. |run| image:: /usage/images/run.png 62 | .. |run_small| image:: /usage/images/run_small.png 63 | .. |scroll_lock_off| image:: /usage/images/scroll_lock_off.png 64 | .. |scroll_lock_off_small| image:: /usage/images/scroll_lock_off_small.png 65 | .. |scroll_lock_on| image:: /usage/images/scroll_lock_on.png 66 | .. |scroll_lock_on_small| image:: /usage/images/scroll_lock_on_small.png 67 | .. |send_cad| image:: /usage/images/send_cad.png 68 | .. |send_cad_small| image:: /usage/images/send_cad_small.png 69 | .. |send_cae| image:: /usage/images/send_cae.png 70 | .. |send_cae_small| image:: /usage/images/send_cae_small.png 71 | .. |settings| image:: /usage/images/settings.png 72 | .. |settings_small| image:: /usage/images/settings_small.png 73 | .. |sound| image:: /usage/images/sound.png 74 | .. |sound_small| image:: /usage/images/sound_small.png 75 | .. |storage_controllers| image:: /usage/images/storage_controllers.png 76 | .. |storage_controllers_small| image:: /usage/images/storage_controllers_small.png 77 | .. |warning| image:: /usage/images/warning.png 78 | .. |warning_small| image:: /usage/images/warning_small.png 79 | .. |zip| image:: /usage/images/zip.png 80 | .. |zip_small| image:: /usage/images/zip_small.png 81 | -------------------------------------------------------------------------------- /index.rst: -------------------------------------------------------------------------------- 1 | =========== 2 | About 86Box 3 | =========== 4 | `86Box `_ is an IBM PC system emulator that specializes in running old 5 | operating systems and software designed for IBM PC systems and compatibles 6 | from 1981 through fairly recent system designs based on the PCI bus. 7 | 8 | 86Box is released under the GNU General Public License, version 2 or later. 9 | For more information, see the `COPYING file `_. 10 | 11 | The project maintainer is `OBattler `_. 12 | 13 | If you need a configuration manager for 86Box, use the `Avalonia 86 `_, our 14 | officially endorsed 86Box configuration manager, developed by notBald (`notBald `_). 15 | Please note that Avalonia 86 currently only works on Windows and Linux. 16 | 17 | ========= 18 | Community 19 | ========= 20 | We operate an `IRC channel `_ and a `Discord server `_ for discussing anything related 21 | to retro computing and, of course, 86Box. We look forward to hearing from you! 22 | 23 | | Additionally, subscribe to our `YouTube channel `_ for content such as installation videos, and follow us on `Twitter `_ for occasional updates and fun facts. 24 | | For more links, visit our `official website `_. 25 | 26 | ======== 27 | Contents 28 | ======== 29 | 30 | .. toctree:: 31 | :maxdepth: 1 32 | :caption: Using 86Box 33 | 34 | usage/gettingstarted 35 | usage/faq 36 | usage/roms 37 | usage/menubar 38 | usage/toolbar 39 | usage/statusbar 40 | settings/index 41 | 42 | .. toctree:: 43 | :maxdepth: 1 44 | :caption: Emulated hardware 45 | 46 | hardware/machinespecific 47 | hardware/keyboard 48 | hardware/diskimages 49 | hardware/ideterqua 50 | hardware/network 51 | hardware/isabugger 52 | 53 | .. toctree:: 54 | :maxdepth: 1 55 | :caption: Development 56 | 57 | dev/buildguide 58 | dev/builds 59 | dev/api/index 60 | dev/formats/index 61 | -------------------------------------------------------------------------------- /make.bat: -------------------------------------------------------------------------------- 1 | @ECHO OFF 2 | 3 | pushd %~dp0 4 | 5 | REM Command file for Sphinx documentation 6 | 7 | if "%SPHINXBUILD%" == "" ( 8 | set SPHINXBUILD=sphinx-build 9 | ) 10 | set SOURCEDIR=. 11 | set BUILDDIR=_build 12 | 13 | if "%1" == "" goto help 14 | 15 | %SPHINXBUILD% >NUL 2>NUL 16 | if errorlevel 9009 ( 17 | echo. 18 | echo.The 'sphinx-build' command was not found. Make sure you have Sphinx 19 | echo.installed, then set the SPHINXBUILD environment variable to point 20 | echo.to the full path of the 'sphinx-build' executable. Alternatively you 21 | echo.may add the Sphinx directory to PATH. 22 | echo. 23 | echo.If you don't have Sphinx installed, grab it from 24 | echo.http://sphinx-doc.org/ 25 | exit /b 1 26 | ) 27 | 28 | %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% 29 | goto end 30 | 31 | :help 32 | %SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% 33 | 34 | :end 35 | popd 36 | -------------------------------------------------------------------------------- /requirements.txt: -------------------------------------------------------------------------------- 1 | Sphinx==8.2.3 2 | sphinx-rtd-theme==3.0.2 3 | linuxdoc==20240924 4 | -------------------------------------------------------------------------------- /settings/display.rst: -------------------------------------------------------------------------------- 1 | .. include:: /include.rst 2 | 3 | |display| Display 4 | ================= 5 | 6 | The **Display** page contains settings related to the emulated machine's 2D and 3D video cards. 7 | 8 | Video 9 | ----- 10 | 11 | Video card to emulate. This box only lists cards supported by the machine's expansion buses. On machines equipped with an onboard video chip, the *Internal* option enables the onboard video. 12 | 13 | The *Configure* button opens a new window with settings specific to the selected video card, such as the amount of video memory. 14 | 15 | Video #2 16 | -------- 17 | 18 | Optional secondary video card to emulate. Only the **MDA**, **Hercules**, **Hercules Plus** and a limited set of **PCI VGA** cards are currently supported as secondary options. The secondary card's video output is displayed on a separate window. 19 | 20 | As with the primary card above, the *Configure* button can be used to configure the selected card. 21 | 22 | Voodoo Graphics 23 | --------------- 24 | 25 | Emulate a **3dfx Voodoo** add-on 3D accelerator, connected to both the PCI bus and the video card selected above. 26 | 27 | .. note:: The **Voodoo Banshee** and **Voodoo 3** are independent video cards, which are not found here; they must be selected on the :ref:`settings/display:Video` box above, and this Voodoo Graphics option **cannot be selected** alongside them. For these cards, the *Configure* button next to the :ref:`settings/display:Video` box provides similar settings to the ones listed below. 28 | 29 | The *Configure* button provides the following settings: 30 | 31 | * **Voodoo type:** type of Voodoo card to emulate. 32 | 33 | * **Voodoo Graphics:** the original Voodoo model, with a single Texture Mapping Unit operating at 50 MHz. 34 | * **Obsidian SB50 + Amethyst:** a variant of the Voodoo Graphics, with two Texture Mapping Units operating at 50 MHz. 35 | * **Voodoo 2:** the second Voodoo model, with two Texture Mapping Units operating at 90 MHz, as well as SLI support. 36 | 37 | * **Framebuffer memory size** / **Texture memory size**: amount of video memory for the Frame Buffer Interface and Texture Mapping Unit(s), respectively. 38 | * **Bilinear filtering:** apply bilinear filtering to smooth out textures displayed on screen. 39 | * **Screen Filter:** apply a filter to make the screen picture resemble the DAC (digital-to-analog converter) output of a real Voodoo card. 40 | * **Render threads:** split the workloads of each Voodoo card into different CPU threads for faster emulation. The recommended amount of render threads depends on your host system's CPU core count, and whether or not Voodoo 2 SLI is enabled: 41 | 42 | +----------+--------------------------+ 43 | |Host cores|Recommended render threads| 44 | | +-----------+--------------+ 45 | | |Single card|Voodoo 2 SLI | 46 | +==========+===========+==============+ 47 | |2 |1 |1 | 48 | +----------+-----------+--------------+ 49 | |4 |2 |1 | 50 | +----------+-----------+--------------+ 51 | |6 or 8 |4 |2 | 52 | +----------+-----------+--------------+ 53 | |10 or more|4 |4 | 54 | +----------+-----------+--------------+ 55 | 56 | * **SLI:** add a second Voodoo 2 card to the system, connected to the first one through a Scan Line Interleave (SLI) interface. 57 | * **Dynamic Recompiler:** enable the Voodoo recompiler for faster emulation. 58 | 59 | IBM 8514/A / XGA Graphics 60 | ------------------------- 61 | 62 | Emulate an **IBM 8514/A** or **XGA** add-on graphics accelerator. Both the original IBM cards for the MCA bus and generic clone cards for the ISA bus are available; the correct card is automatically selected based on the machine's supported expansion buses. 63 | 64 | The *Configure* button next to the XGA opens a new window where the card type (**XGA-1** or **XGA-2**) and initial BIOS address can be configured. 65 | 66 | .. note:: Pairing the 8514/A and XGA with each other or with video cards from **ATI** or **S3** may result in compatibility issues, as each card implements a set of 8514/A features. 67 | -------------------------------------------------------------------------------- /settings/floppycdrom.rst: -------------------------------------------------------------------------------- 1 | .. include:: /include.rst 2 | 3 | |floppy_and_cdrom_drives| Floppy & CD-ROM drives 4 | ================================================ 5 | 6 | The **Floppy & CD-ROM drives** page contains settings related to the emulated machine's base removable storage drives. 7 | 8 | Floppy drives 9 | ------------- 10 | 11 | Up to four floppy disk drives can be attached to the emulated system, although not all machines provide BIOS support for more than two drives. The following settings apply to the selected drive: 12 | 13 | * **Type:** floppy drive to emulate. Some types have special properties and should only be used in very specific applications: 14 | 15 | * **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 NEC PC-98 3.5" disks if the emulated machine's BIOS supports 3-mode operation. 16 | * **3.5" 1.44M PC-98:** NEC PC-98 drive, which is 3-mode and inverts the polarity of the Density Select pin. 17 | 18 | * **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. 19 | * **Check BPB:** if unchecked, 86Box will ignore the `DOS 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. 20 | 21 | .. 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`. 22 | 23 | Floppy disk images can be inserted and removed through the :ref:`status bar ` or :ref:`Media menu `. 24 | 25 | CD-ROM drives 26 | ------------- 27 | 28 | Up to eight CD-ROM / DVD-ROM optical disc drives can be attached to the emulated system. The following settings apply to the selected drive: 29 | 30 | * **Bus:** storage bus to attach the drive to. ATAPI (IDE) and SCSI are supported. 31 | * **Channel**/**ID:** where to attach the drive on the selected storage bus. See :ref:`settings/hdd:Adding a new disk` for more information. 32 | * **Speed:** maximum transfer speed for the drive. Up to 72x is supported. 33 | * **Type:** CD-ROM drive model to identify as. A list of drive models to choose from is provided. 34 | 35 | .. note:: 36 | * Some emulated machines have manufacturer restore discs locked to a specific drive model. 37 | * The default **86Box 86B_CD 3.50** model also supports DVDs; the **86B_DVD 4.30** differs only in model name and reported capabilities. 38 | * The **86Box 86B_CD 1.00** model emulates early versions of the ATAPI and SCSI standards as required by older drivers. 39 | 40 | CD-ROM / DVD-ROM disc images or host drives can be inserted and removed through the :ref:`status bar ` or :ref:`Media menu `. 41 | -------------------------------------------------------------------------------- /settings/hdd.rst: -------------------------------------------------------------------------------- 1 | .. include:: /include.rst 2 | 3 | |hard_disk| Hard disks 4 | ====================== 5 | 6 | The **Hard disks** page contains settings related to the emulated machine's fixed disks. 7 | 8 | Hard disk list 9 | -------------- 10 | 11 | All hard disks attached to the emulated system are listed, with the following information: 12 | 13 | * **Bus:** storage bus the disk is attached to, as well as the disk's bus channel or ID. These can be changed through the *Bus* and *Channel*/*ID* boxes below the list. 14 | * **File:** path to the disk image file. 15 | * **C/H/S:** disk size in cylinders, heads and sectors, respectively. 16 | * **MB:** disk size in megabytes. 17 | * **Model:** :ref:`emulated model profile ` for the disk. 18 | 19 | Model 20 | ----- 21 | 22 | The *Model* box below the hard disk list determines the **disk model** to emulate. Model profiles adjust the disk's identification data, as well as its performance according to rotation speed, physical layout and cache size. Generic profiles adjust performance to match an average period-correct disk, while the **RAM Disk** profile runs the disk as fast as the host can manage. 23 | 24 | Adding a new disk 25 | ----------------- 26 | 27 | The *New...* button opens a new window allowing you to create an existing hard disk image file. 28 | 29 | * **File name:** where to save the disk image file. See :ref:`hardware/diskimages:Hard disk images` for a list of supported image formats. 30 | * **Cylinders/Heads/Sectors:** CHS parameters for the disk image. These boxes control the *Size (MB)* box below. 31 | * **Size (MB):** the disk image's size in MB. This box controls the *Cylinders*, *Heads* and *Sectors* boxes above. There are limits to how big a hard disk image can be; see :ref:`hardware/diskimages:Hard disk size limits` for more information. 32 | * **Bus:** storage bus to attach the disk to. 33 | * **Channel**/**ID:** where to attach the disk on the selected storage bus. Channels/IDs that are already in use cannot be selected. 34 | 35 | * On IDE disks, the first number corresponds to the IDE channel, and the second number corresponds to the Master/Slave position: 36 | 37 | +-----+----------+------+ 38 | |Value|Channel |Device| 39 | +=====+==========+======+ 40 | |0:0 |Primary |Master| 41 | +-----+----------+------+ 42 | |0:1 |Primary |Slave | 43 | +-----+----------+------+ 44 | |1:0 |Secondary |Master| 45 | +-----+----------+------+ 46 | |1:1 |Secondary |Slave | 47 | +-----+----------+------+ 48 | |2:0 |Tertiary |Master| 49 | +-----+----------+------+ 50 | |2:1 |Tertiary |Slave | 51 | +-----+----------+------+ 52 | |3:0 |Quaternary|Master| 53 | +-----+----------+------+ 54 | |3:1 |Quaternary|Slave | 55 | +-----+----------+------+ 56 | 57 | * On SCSI disks, the first number corresponds to the controller's index, starting from 0 and following the order of: on-board SCSI controllers if present, then :ref:`sound cards ` with SCSI if present, then :ref:`configured SCSI controllers `; the second number is the SCSI ID within that controller: 58 | 59 | +-----+------------+-------+ 60 | |Value|Controller |SCSI ID| 61 | +=====+============+=======+ 62 | |0:00 |Controller 1|0 | 63 | +-----+ +-------+ 64 | ||vel|| ||vel| | 65 | +-----+ +-------+ 66 | |0:15 | |15 | 67 | +-----+------------+-------+ 68 | |1:00 |Controller 2|0 | 69 | +-----+ +-------+ 70 | ||vel|| ||vel| | 71 | +-----+ +-------+ 72 | |1:15 | |15 | 73 | +-----+------------+-------+ 74 | |2:00 |Controller 3|0 | 75 | +-----+ +-------+ 76 | ||vel|| ||vel| | 77 | +-----+ +-------+ 78 | |2:15 | |15 | 79 | +-----+------------+-------+ 80 | |3:00 |Controller 4|0 | 81 | +-----+ +-------+ 82 | ||vel|| ||vel| | 83 | +-----+ +-------+ 84 | |3:15 | |15 | 85 | +-----+------------+-------+ 86 | 87 | 88 | * On MFM/RLL, XTA and ESDI disks, the second number is 0 for the first drive on the controller, and 1 for the second drive. 89 | 90 | .. note:: If the disk is attached to a channel or controller that doesn't exist, such as the tertiary IDE channel with no tertiary IDE controller present, it will be effectively disabled. 91 | 92 | Press the *OK* button to create the disk image file, or *Cancel* to close the window without adding the disk. 93 | 94 | Adding an existing disk 95 | ----------------------- 96 | 97 | The *Existing...* button opens a similar window to the *New...* button, except that it lets you select an existing disk image file. The CHS parameters are guessed from the image's file size, or the file header if the image is of a format which contains a header. 98 | 99 | After selecting the image file and checking if the parameters are correct, select the *Bus* and *Channel*/*ID* for the hard disk and press *OK* to add it. Press *Cancel* to close the window without adding the disk. 100 | 101 | Removing a disk 102 | --------------- 103 | 104 | Select a disk on the list and press *Remove* to remove it. 105 | -------------------------------------------------------------------------------- /settings/index.rst: -------------------------------------------------------------------------------- 1 | .. include:: /include.rst 2 | 3 | Settings 4 | ======== 5 | 6 | The *Settings* window allows you to configure the emulated machine. 7 | 8 | If any changes were made to the settings, you will be asked whether or not you want to save the changes upon pressing *OK* or closing the window. Saving changes will hard reset the emulated machine. Press *Cancel* to immediately discard all changes. 9 | 10 | .. raw:: html 11 | 12 | 47 | 48 | .. toctree:: 49 | :maxdepth: 1 50 | :caption: Settings pages 51 | 52 | machine 53 | display 54 | input 55 | sound 56 | network 57 | ports 58 | storage 59 | hdd 60 | floppycdrom 61 | removable 62 | peripherals 63 | -------------------------------------------------------------------------------- /settings/input.rst: -------------------------------------------------------------------------------- 1 | .. include:: /include.rst 2 | 3 | |input_devices| Input devices 4 | ============================= 5 | 6 | The **Input devices** page contains settings related to the emulated machine's mouse, joysticks and other input devices. 7 | 8 | Mouse 9 | ----- 10 | 11 | Emulate a pointing device. The following types are supported: 12 | 13 | * **Bus mouse:** ISA expansion card with a mouse interface. The I/O port and IRQ used by the card are configurable. 14 | * **Serial mouse:** connected to the serial port of your choosing. 15 | * **Serial tablet:** also connected to a serial port, but providing absolute (seamless) input on supported operating systems and/or applications. 16 | * **PS/2 mouse:** connected to the PS/2 port. Only available on machines with a PS/2 mouse port. 17 | 18 | The *Configure* button opens a new window with settings specific to the selected device type, such as the number of buttons, or the serial port for a serial mouse or tablet. 19 | 20 | .. note:: 21 | * Serial pointing devices require the configured serial port to be enabled on the :ref:`Ports page `. 22 | * The middle button cannot be used to release mouse capture when emulating a mouse with 3 or more buttons. 23 | 24 | Joystick 25 | -------- 26 | 27 | Emulate one or more game port controller(s). The following controller types are supported: 28 | 29 | * **None:** no controller connected. 30 | * **2-axis, 2-button joystick(s):** up to two controllers, each with two buttons and an analog stick. 31 | * **2-axis, 4-button joystick:** single controller with four buttons and an analog stick. 32 | * **3-axis, 2-button joystick:** single controller with two buttons and an analog stick and a throttle. 33 | * **3-axis, 4-button joystick:** single controller with four buttons and an analog stick and a throttle. 34 | * **2-axis, 6-button joystick:** single controller with four regular buttons, two additional buttons mapped to the third and fourth axes, and an analog stick. 35 | * **2-axis, 8-button joystick:** single controller with four regular buttons, four additional buttons mapped to the third and fourth axes, and an analog stick. 36 | * **4-axis 4-button joystick:** single controller with four buttons and two analog sticks (or four axes). 37 | * **CH Flightstick Pro:** flight controller with four buttons, three axes and a POV hat. 38 | * **Microsoft SideWinder Pad:** up to four controllers, each with 10 buttons and a directional pad. Not compatible with standard game port joysticks; requires a driver in the emulated machine. 39 | * **Thrustmaster Flight Control System:** flight controller with four buttons, two axes and a POV hat. 40 | 41 | .. note:: A generic game port card is emulated if the machine has no game ports (either built-in or as part of a Plug and Play or PCI sound card) to accomodate the selected controller. This generic card uses the default I/O ports 200-207h, which can be changed through ISA Plug and Play. On IBM PCjr and PS/1 machines, the generic card uses port 201h only and has no Plug and Play capability. 42 | 43 | Joystick 1-4... 44 | --------------- 45 | 46 | Configure the mappings for each emulated game port controller. The *Device* box lists all game controllers connected to the host, while the other boxes allow you to map each axis or button of the emulated controller to the real controller. 47 | 48 | If you're not sure as to what axis or button numbers map to which sticks and buttons on the real controller, use the *Test* feature of Windows' *Game Controllers* control panel (``joy.cpl``) or another controller testing utility for your platform. 49 | 50 | .. note:: XInput controllers are accessed through their DInput emulation mode at the moment. 51 | 52 | Key bindings 53 | ------------ 54 | 55 | View and change keyboard shortcuts for common emulator actions. The *Clear binding* button removes the shortcut associated with the selected action, and the *Bind* button allows for entering a new shortcut. 56 | 57 | .. note:: The F8 + F12 key combination used for releasing mouse capture in previous 86Box versions can no longer be configured as a shortcut. 58 | -------------------------------------------------------------------------------- /settings/machine.rst: -------------------------------------------------------------------------------- 1 | .. include:: /include.rst 2 | 3 | |machine| Machine 4 | ================= 5 | 6 | The **Machine** page contains settings related to the emulated machine as a whole, such as the machine type, CPU type and amount of memory. 7 | 8 | Machine type / Machine 9 | ---------------------- 10 | 11 | Machine/motherboard model to emulate. The *Machine* box lists all available models for the machine class selected on the *Machine type* box. 12 | 13 | The *Configure* button opens a new window with settings specific to the machine, such as BIOS type selection. 14 | 15 | .. note:: Settings for the machine's onboard devices have been moved to the *Configure* buttons at the devices' respective locations; for instance, configuring the amount of installed video memory for an onboard video chip is now done through the *Configure* button next to the :ref:`Display page's Video box ` when the *Internal* option is selected there. 16 | 17 | CPU type / Speed 18 | ---------------- 19 | 20 | Main processor to emulate. The *Speed* box lists all available speed grades for the processor family selected on the *CPU type* box. These boxes only list processor types and speed grades supported by the machine selected above. 21 | 22 | FPU 23 | --- 24 | 25 | Math co-processor to emulate. This box is not available if the processor selected above has an integrated co-processor or lacks support for an external one. 26 | 27 | Wait states 28 | ----------- 29 | 30 | Number of memory wait states to use on a 286- or 386-class processor. This box is not available if any other processor family is selected above. 31 | 32 | PIT mode 33 | -------- 34 | 35 | Programmable Interval Timer emulation mode. **Auto** should cover most use cases, automatically selecting **Fast** mode on 486-class and newer processors or **Slow** mode on older ones. A limited set of timing-sensitive applications require **Slow** mode, which is slower but more accurate. 36 | 37 | Memory 38 | ------ 39 | 40 | Amount of RAM to give the emulated machine. The minimum and maximum allowed amounts of RAM will vary depending on the machine selected above. 41 | 42 | Dynamic Recompiler 43 | ------------------ 44 | 45 | Enable the dynamic recompiler, which provides faster but less accurate CPU emulation. The recompiler is available as an option for 486-class processors, and is mandatory starting with the Pentium. 46 | 47 | Softfloat FPU 48 | ------------- 49 | 50 | 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. 51 | 52 | Time synchronization 53 | -------------------- 54 | 55 | Automatically copy your host system's date and time over to the emulated machine's hardware real-time clock. Synchronization is performed every time the emulated operating system reads the hardware clock to calibrate its own internal clock, which usually happens once on every boot. 56 | 57 | * **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. 58 | * **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. 59 | * **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. 60 | -------------------------------------------------------------------------------- /settings/network.rst: -------------------------------------------------------------------------------- 1 | .. include:: /include.rst 2 | 3 | |network| Network 4 | ================= 5 | 6 | The **Network** page contains settings related to the emulated machine's network connectivity. 7 | 8 | Network Card #1-#4 9 | ------------------ 10 | 11 | Network interface cards to emulate. Up to 4 independent network cards are supported. 12 | 13 | Mode 14 | ^^^^ 15 | 16 | Network emulation mode to use on this card. See :doc:`../hardware/network` for more information on these. 17 | 18 | * **Null Driver:** emulate an empty network. All packets are dropped. 19 | * **PCap:** connects directly to a host network adapter. Similar to the **Bridge** mode on other emulators and virtualizers. 20 | * **SLiRP:** creates a private network with a virtual router. Similar to the **NAT** mode on other emulators and virtualizers. 21 | * **VDE:** attaches to a virtual switch created by :ref:`hardware/network:VDE`. Only available on Linux and macOS hosts. 22 | 23 | .. note:: 24 | If PCap mode is not listed, make sure that: 25 | 26 | * A WinPcap-compatible driver is installed; 27 | * The installed driver is compatible with your version of Windows; 28 | * At least one compatible (wired) network adapter is present. 29 | 30 | Adapter 31 | ^^^^^^^ 32 | 33 | Network card to emulate. Only cards supported by the machine's expansion buses will be listed. 34 | 35 | The *Configure* button opens a new window with settings specific to the selected network card, such as the MAC address for Ethernet cards, and the I/O port and IRQ for ISA cards. 36 | 37 | .. note:: 38 | * The MAC address is partially configurable and always prefixed by an `Organizationally Unique Identifier `_ belonging to the card's manufacturer, such as ``00:E0:4C`` for Realtek. 39 | * The **[LPT] Parallel Port Internet Protocol** network adapter requires a **PLIP Network** device to be attached to a :ref:`parallel port `. 40 | * Settings for the **[COM] Standard Hayes-compliant Modem** are described on :ref:`Networking `. 41 | 42 | Options 43 | ^^^^^^^ 44 | 45 | Settings for the network emulation mode selected above. Only settings relevant to the selected mode will be shown. 46 | 47 | * **Interface:** host network adapter to use in **PCap** mode. 48 | * **VDE Socket:** virtual switch socket path to use in **VDE** mode. See the :ref:`VDE setup guide ` for more information. 49 | -------------------------------------------------------------------------------- /settings/peripherals.rst: -------------------------------------------------------------------------------- 1 | .. include:: /include.rst 2 | 3 | |other_peripherals| Other peripherals 4 | ===================================== 5 | 6 | The **Other peripherals** page contains settings related to disk drive controllers, memory expansions and other expansion cards. 7 | 8 | 9 | ISA RTC 10 | ------- 11 | 12 | Emulate an ISA real-time clock card, for machines without an integrated real-time clock. 13 | 14 | The I/O port and/or IRQ used by the selected controller can be configured through the *Configure* button. 15 | 16 | ISA Memory Expansion 17 | -------------------- 18 | 19 | Add up to four ISA-based memory expansion cards, for machines which support memory expansion through the ISA bus. 20 | 21 | The memory start address and size for each expansion card can be configured through its respective *Configure* button. 22 | 23 | ISABugger 24 | --------- 25 | 26 | 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. 27 | 28 | POST card 29 | --------- 30 | 31 | 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 ` for more information. 32 | 33 | The POST card will automatically use the correct diagnostic I/O ports for the emulated machine: 34 | 35 | .. list-table:: 36 | :header-rows: 1 37 | :widths: 1 999 38 | 39 | * - Port 40 | - Machine types 41 | 42 | * - ``0x10 0x11 0x12`` 43 | - IBM PCjr 44 | 45 | * - ``0x60`` 46 | - IBM XT 47 | 48 | * - ``0x80`` 49 | - IBM AT, clones and the XT-based Xi 8088 50 | 51 | * - ``0x84`` 52 | - Early Compaq 53 | 54 | * - ``0xE0 0xE4`` 55 | - Dell (4-character text display after the port ``0x80`` hex display) 56 | 57 | * - ``0x190`` 58 | - IBM PS/1 and PS/2 not based on the Micro Channel Architecture 59 | 60 | * - ``0x378`` 61 | - Olivetti 62 | 63 | * - ``0x680`` 64 | - Micro Channel Architecture 65 | 66 | * - ``0x5080`` 67 | - ASUS ISA-486C 68 | 69 | .. note:: Some operating systems and applications use port ``0x80`` (which is shared with the POST card on most machines) for other purposes. If you notice the POST code display is flickering and the emulation speed has decreased drastically, try disabling the POST card. 70 | 71 | 86Box Unit Tester 72 | ----------------- 73 | 74 | Emulate a special device for software in the emulated machine to control 86Box for testing purposes. The *Configure* button provides settings specific to this device. 75 | 76 | .. note:: Documentation to be concluded. 77 | -------------------------------------------------------------------------------- /settings/ports.rst: -------------------------------------------------------------------------------- 1 | .. include:: /include.rst 2 | 3 | |ports| Ports (COM & LPT) 4 | ========================= 5 | 6 | The **Ports (COM & LPT)** page contains settings related to the emulated machine's I/O ports. 7 | 8 | LPT1-4 Device 9 | ------------- 10 | 11 | Emulated device to connect to the given parallel (LPT) port. 12 | 13 | * **None:** no device connected. 14 | * **Disney Sound Source:** sound device with a resistor ladder DAC (digital-to-analog converter) and FIFO, supported by many games. 15 | * **LPT DAC / Covox Speech Thing:** sound device with a simple resistor ladder DAC, supported by many games (through compatibility with the *Disney Sound Source* above), demos and trackers. 16 | * **Stereo LPT DAC:** stereo version of the LPT DAC, using the *Strobe* pin to select the active output channel. 17 | * **Generic Text Printer:** simple printer capable of outputting text only. 18 | 19 | * Printed documents are saved as .txt files in the ``printer`` subdirectory found in the emulated machine's directory. 20 | 21 | * **Generic ESC/P Dot-Matrix:** EPSON ESC/P-compatible printer. 22 | 23 | * Printed pages are saved as .png files in the ``printer`` subdirectory found in the emulated machine's directory. 24 | * Use the **EPSON LQ-2500** printer driver for best results. 25 | 26 | * **Generic PostScript Printer:** PostScript-compatible printer with PDF output. 27 | 28 | * Printed documents are saved as .ps files in the ``printer`` subdirectory found in the emulated machine's directory. These files are automatically converted to .pdf once printing is completed. 29 | * The original .ps files may remain in the directory if PDF conversion fails, or (on Windows hosts) if the included ``gsdll32.dll`` or ``gsdll64.dll`` file is missing from the 86Box directory. 30 | * Use the generic PostScript printer driver provided by your operating system. 31 | * Windows 95 and newer do not have a generic PostScript driver; use the **Apple LaserWriter IIf** driver for grayscale, or the **Apple Color LW 12/660 PS** driver for color. 32 | 33 | * **PLIP Network:** A `Parallel Line Internet Protocol `_ cable connected to the :doc:`emulated network `. 34 | 35 | * The :ref:`emulated network adapter ` must also be set to **[LPT] PLIP**. 36 | * PLIP is compatible with the DOS ``plip.com`` packet driver and the Linux ``plip`` driver (only with interrupts enabled). It is not compatible with the Windows *Direct Cable Connection* feature or any other parallel port networking implementations. 37 | * PLIP only works with the **SLiRP** :ref:`network type ` due to its point-to-point nature. 38 | 39 | Serial port 1-4 40 | --------------- 41 | 42 | Enable emulation of serial ports ranging from COM1 to COM4. Any ports not provided by the machine's motherboard will be emulated as generic ISA or VLB serial cards. 43 | 44 | Parallel port 1-4 45 | ----------------- 46 | 47 | Enable emulation of parallel ports ranging from LPT1 to LPT4. Any ports not provided by the machine's motherboard will be emulated as generic ISA or VLB parallel cards. 48 | 49 | .. note:: The 4th parallel port is not widely supported. It is located at I/O port 268h. 50 | 51 | Serial port passthrough 1-4 52 | --------------------------- 53 | 54 | Connect emulated serial ports to named pipes or serial ports on the host. Each instance corresponds to one of the 4 emulates serial ports. 55 | 56 | The *Configure* button next to each passthrough instance opens a new window with settings specific to it, such as the named pipe or serial port to use. 57 | 58 | .. note:: Passthrough will not operate correctly if the selected serial port is taken by a :ref:`serial mouse `. 59 | -------------------------------------------------------------------------------- /settings/removable.rst: -------------------------------------------------------------------------------- 1 | .. include:: /include.rst 2 | 3 | |other_removable_devices| Other removable devices 4 | ================================================= 5 | 6 | The **Other removable devices** page contains settings related to the emulated machine's additional removable storage drives. 7 | 8 | MO / ZIP drives 9 | --------------- 10 | 11 | Up to four Magneto-Optical and four Iomega ZIP disk drives can be attached to the emulated system. The following settings apply to the selected drive: 12 | 13 | * **Bus:** storage bus to attach the drive to. ATAPI (IDE) and SCSI are supported. 14 | * **Channel**/**ID:** where to attach the drive on the selected storage bus. See :ref:`settings/hdd:Adding a new disk` for more information. 15 | * **Type** (MO only): drive model to identify as. A list of drive models to choose from is provided. Each model supports different types of MO media, while the *86BOX* model supports all types. 16 | * **ZIP 250** (ZIP only): enable the drive to read and write 250 MB ZIP disks. 17 | 18 | MO / ZIP disk images can be inserted and removed through the :ref:`status bar ` or :ref:`Media menu `. 19 | -------------------------------------------------------------------------------- /settings/sound.rst: -------------------------------------------------------------------------------- 1 | .. include:: /include.rst 2 | 3 | |sound| Sound 4 | ============= 5 | 6 | The **Sound** page contains settings related to the emulated machine's audio hardware. 7 | 8 | Parallel port sound devices such as the **Disney Sound Source** and **Covox Speech Thing** are not present on this page; they can be configured through the :ref:`Ports page `. 9 | 10 | Sound card #1-#4 11 | ---------------- 12 | 13 | Sound cards to emulate. Up to 4 different sound cards are supported. Only cards supported by the machine's expansion buses will be listed. On machines equipped with an onboard sound chip, the *Internal* option for sound card #1 enables the onboard sound. 14 | 15 | The *Configure* button opens a new window with settings specific to the selected sound card, such as the I/O ports, IRQ and DMA channels for ISA cards. 16 | 17 | Emulation for the Yamaha OPL series of synthesizers (used by many of the emulated cards) is provided by a modified `Nuked OPL3 `_ or `ymfm `_ library, per the :ref:`selection below `. MOS Technology 6581 SID emulation for the Innovation SSI-2001 and The Entertainer is provided by the reSIDfp component of the `libsidplayfp `_ library. General Instrument AY-3-8913 emulation for the Mindscape Music Board is provided by the `Ayumi `_ library. 18 | 19 | .. note:: The **Innovation SSI-2001**, **CMS / Game Blaster** and **Gravis Ultrasound** are now selectable here, replacing the previous separate options for each. 20 | 21 | MIDI Out Device 22 | --------------- 23 | 24 | Device to output MIDI music to, for sound cards equipped with an external MIDI output. 25 | 26 | * **None:** don't output MIDI music. 27 | * **FluidSynth:** a software soundfont synthesizer. Selecting a soundfont file is required; there will be no synthesizer output if no soundfont is configured. 28 | * **Roland MT-32**/**CM-32L Emulation:** emulate a Roland synthesizer module. Emulation is provided by the `Munt `_ library. 29 | * **System MIDI:** output to a MIDI device on the host system, such as the Windows software synthesizer or a USB MIDI adapter. 30 | 31 | The *Configure* button opens a new window with settings specific to the selected output device, such as the soundfont to use for *FluidSynth* and the host MIDI device to use for *System MIDI*. 32 | 33 | MIDI In Device 34 | -------------- 35 | 36 | Device to receive MIDI music from, for sound cards equipped with an external MIDI input. 37 | 38 | * **None:** don't receive MIDI music. 39 | * **System MIDI:** receive from a MIDI device on the host system, such as a USB MIDI adapter. 40 | 41 | The *Configure* button opens a new window with settings specific to the selected input device, such as the host MIDI device to use for *System MIDI*. 42 | 43 | Standalone MPU-401 44 | ------------------ 45 | 46 | Emulate a standalone **Roland MIDI Processing Unit** ISA card, which allows for MIDI input and output without a MPU-401-equipped sound card, and for running the few applications which require *intelligent mode* capability. 47 | 48 | The I/O port and IRQ can be configured through the *Configure* button. 49 | 50 | Use FLOAT32 sound 51 | ----------------- 52 | 53 | 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. 54 | 55 | FM synth driver 56 | --------------- 57 | 58 | Yamaha OPL2/3 emulation back-end to use. **Nuked** is the default, while **YMFM** may improve emulation performance at the cost of accuracy. 59 | 60 | .. note:: **YMFM** is always used for OPL4 emulation on sound cards equipped with that synthesizer. 61 | -------------------------------------------------------------------------------- /settings/storage.rst: -------------------------------------------------------------------------------- 1 | .. include:: /include.rst 2 | 3 | |storage_controllers| Storage controllers 4 | ========================================= 5 | 6 | The **Storage controllers** page contains settings related to the emulated machine's disk drive controllers. 7 | 8 | HD Controller 9 | ------------- 10 | 11 | Hard disk drive controller card to emulate. This box only lists cards supported by the machine's expansion buses. MFM, RLL, ESDI and IDE controllers are available. Selecting an IDE controller is not required for machines with onboard IDE. 12 | 13 | The *Configure* button opens a new window with settings specific to the selected controller card, such as the BIOS option ROM address. 14 | 15 | FD Controller 16 | ------------- 17 | 18 | Floppy disk drive controller card to emulate. Selecting a controller is not required, unless you wish to use one of the add-on controllers for adding high-density 1.44M floppy support to XT machines. 19 | 20 | The BIOS option ROM address used by the selected controller can be configured through the *Settings* button. 21 | 22 | Tertiary / Quaternary IDE Controller 23 | ------------------------------------ 24 | 25 | Add a third or fourth (respectively) IDE channel to the emulated machine, through a generic ISA or VLB IDE controller card. 26 | 27 | The IRQ used by each controller can be configured through its respective *Settings* button. 28 | 29 | .. note:: The tertiary and quaternary controllers are not Plug and Play compliant by default; they may require manual configuration of emulated operating systems, and may not be bootable. See :doc:`../hardware/ideterqua` for more information. 30 | 31 | SCSI 32 | ---- 33 | 34 | SCSI host bus adapter cards to emulate. Up to 4 SCSI cards are supported. The selection boxes only list cards supported by the machine's expansion buses. 35 | 36 | The *Configure* buttons open a new window with settings specific to the corresponding SCSI card, such as the I/O port and IRQ for ISA cards. 37 | 38 | Cassette 39 | -------- 40 | 41 | Enable IBM cassette tape emulation. Only available on machines with a cassette port. The cassette deck can be controlled through the :ref:`status bar ` or :ref:`Media menu `. 42 | 43 | Vision Systems LBA Enhancer 44 | --------------------------- 45 | 46 | Add an IDE Enhancer option ROM card, which can help work around the :ref:`hard disk size limits ` on many older machines. Hard disks up to 8055 MB (16367 cylinders, 16 heads, 63 sectors) in size are supported; they must be manually configured to **8 cylinders, 8 heads and 8 sectors** on the machine's BIOS setup utility for the Enhancer to handle them. 47 | 48 | The BIOS option ROM address used can be configured through the *Settings* button. 49 | -------------------------------------------------------------------------------- /usage/faq.rst: -------------------------------------------------------------------------------- 1 | Frequently asked questions 2 | ========================== 3 | 4 | What is the difference between 86Box and applications like VirtualBox or Virtual PC? 5 | ------------------------------------------------------------------------------------ 6 | 7 | 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. 8 | 9 | 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 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. 10 | 11 | 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 run 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. 12 | 13 | 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. 14 | 15 | What is the difference between 86Box and QEMU? 16 | ---------------------------------------------- 17 | 18 | 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. 19 | 20 | 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. 21 | 22 | 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. 23 | 24 | What is the difference between 86Box and PCem? 25 | ---------------------------------------------- 26 | 27 | 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. 28 | 29 | 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. 30 | 31 | 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. 32 | 33 | My virtual machine does not run at 100% speed, what do I do? 34 | ------------------------------------------------------------ 35 | 36 | 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. 37 | 38 | 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. 39 | 40 | What is the top VM configuration my system will handle? 41 | ------------------------------------------------------- 42 | 43 | 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. 44 | 45 | Therefore, the best way to optimize your virtual machine configuration is simply trial and error. 46 | 47 | Are you going to add emulation of the Pentium 3 and/or newer CPUs? 48 | ------------------------------------------------------------------ 49 | 50 | 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! 51 | 52 | For further reading, team member RichardG wrote a `blog post `_ that goes into the details of what makes the emulation of newer CPUs so controversial. 53 | -------------------------------------------------------------------------------- /usage/gettingstarted.rst: -------------------------------------------------------------------------------- 1 | Getting started 2 | =============== 3 | 4 | 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. 5 | 6 | .. rubric:: Step 1: Get the ROM set 7 | 8 | 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 `. 9 | 10 | .. rubric:: Step 2: Meet the main window 11 | 12 | Once you got the romset in the right place, you can start ``86Box.exe``. The main window has three important areas: 13 | 14 | * **The menu bar at the top**, where most controls and options are located. See :doc:`menubar` for more information. 15 | * **The display area in the middle**, which is where the display output from the emulated machine will be rendered. 16 | * **The status bar at the bottom**, containing icons for quickly accessing the configured peripheral devices. See :doc:`statusbar` for more information. 17 | 18 | .. rubric:: Step 3: Configure the hardware 19 | 20 | When you start an emulated machine, you probably want to configure it with the hardware options you want. This is much like putting together the hardware components to build a PC. To do this, go to the *Tools* menu and select *Settings*. This will bring up the *Settings* window, which has many options to choose from, split into :doc:`a handful of categories <../settings/index>`. 21 | 22 | .. rubric:: Step 4: Configure the BIOS 23 | 24 | Once you've selected the hardware components you wish to emulate, you need to make sure they're properly configured. This is done through the system BIOS, the same way it's done on a real computer. The specifics of this will of course differ from one machine to another, but generally speaking, you need to know how to enter the BIOS, which options to change, and which options to leave alone. 25 | 26 | .. rubric:: Step 5: Mount some images 27 | 28 | Now that you've configured everything, you're ready to run some software in your emulated machine. Maybe you want to install an operating system or play a booter game. In any case, you'll have to mount some virtual media to get going. You can do this with the icons in the :doc:`status bar `. Icons representing removable media appear semi-transparent when their associated drive is empty, and fully opaque when media is inserted. 29 | 30 | When you want to eject virtual media, click on the particular icon again and select *Eject* (for floppy and ZIP disks) or *Empty* (for CD-ROMs). The icon becomes semi-transparent again. 31 | 32 | .. rubric:: Step 6: Mouse and keyboard interaction 33 | 34 | Now you're ready to do some stuff inside the emulated machine. Keyboard input is redirected there automatically whenever the emulator window has focus. All key presses and combinations will be redirected to the emulated machine. 35 | 36 | 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. 37 | 38 | 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. 39 | 40 | .. rubric:: Step 7: What now? 41 | 42 | If you made it this far, you got the basics of using 86Box, but there's more features and options to explore. For example, you can try out `Avalonia 86 `_ for easier management of multiple emulated machines. You can see what's under the *View* menu, or look at some of the more obscure options in the *Settings* window. 43 | 44 | You may eventually encounter the need to get files *into* your machine. Please see :ref:`this section for information on disk image formats` and :ref:`this section on creating and using disk images`. 45 | 46 | Keep in mind that because 86Box is constantly in development, various problems will come and go. If you think something's not working the way it should, consider `submitting an issue on GitHub `_ or joining official support channels on Discord or IRC. 47 | 48 | Have fun! 49 | -------------------------------------------------------------------------------- /usage/images/acpi_shutdown.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/acpi_shutdown.png -------------------------------------------------------------------------------- /usage/images/acpi_shutdown_small.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/acpi_shutdown_small.png -------------------------------------------------------------------------------- /usage/images/caps_lock_off.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/caps_lock_off.png -------------------------------------------------------------------------------- /usage/images/caps_lock_off_small.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/caps_lock_off_small.png -------------------------------------------------------------------------------- /usage/images/caps_lock_on.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/caps_lock_on.png -------------------------------------------------------------------------------- /usage/images/caps_lock_on_small.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/caps_lock_on_small.png -------------------------------------------------------------------------------- /usage/images/cartridge.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/cartridge.png -------------------------------------------------------------------------------- /usage/images/cartridge_small.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/cartridge_small.png -------------------------------------------------------------------------------- /usage/images/cassette.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/cassette.png -------------------------------------------------------------------------------- /usage/images/cassette_small.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/cassette_small.png -------------------------------------------------------------------------------- /usage/images/cdrom.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/cdrom.png -------------------------------------------------------------------------------- /usage/images/cdrom_folder.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/cdrom_folder.png -------------------------------------------------------------------------------- /usage/images/cdrom_folder_small.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/cdrom_folder_small.png -------------------------------------------------------------------------------- /usage/images/cdrom_host.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/cdrom_host.png -------------------------------------------------------------------------------- /usage/images/cdrom_host_small.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/cdrom_host_small.png -------------------------------------------------------------------------------- /usage/images/cdrom_image.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/cdrom_image.png -------------------------------------------------------------------------------- /usage/images/cdrom_image_small.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/cdrom_image_small.png -------------------------------------------------------------------------------- /usage/images/cdrom_small.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/cdrom_small.png -------------------------------------------------------------------------------- /usage/images/display.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/display.png -------------------------------------------------------------------------------- /usage/images/display_small.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/display_small.png -------------------------------------------------------------------------------- /usage/images/floppy_35.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/floppy_35.png -------------------------------------------------------------------------------- /usage/images/floppy_35_small.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/floppy_35_small.png -------------------------------------------------------------------------------- /usage/images/floppy_525.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/floppy_525.png -------------------------------------------------------------------------------- /usage/images/floppy_525_small.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/floppy_525_small.png -------------------------------------------------------------------------------- /usage/images/floppy_and_cdrom_drives.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/floppy_and_cdrom_drives.png -------------------------------------------------------------------------------- /usage/images/floppy_and_cdrom_drives_small.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/floppy_and_cdrom_drives_small.png -------------------------------------------------------------------------------- /usage/images/hard_disk.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/hard_disk.png -------------------------------------------------------------------------------- /usage/images/hard_disk_small.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/hard_disk_small.png -------------------------------------------------------------------------------- /usage/images/hard_reset.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/hard_reset.png -------------------------------------------------------------------------------- /usage/images/hard_reset_small.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/hard_reset_small.png -------------------------------------------------------------------------------- /usage/images/input_devices.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/input_devices.png -------------------------------------------------------------------------------- /usage/images/input_devices_small.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/input_devices_small.png -------------------------------------------------------------------------------- /usage/images/kana_lock_off.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/kana_lock_off.png -------------------------------------------------------------------------------- /usage/images/kana_lock_off_small.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/kana_lock_off_small.png -------------------------------------------------------------------------------- /usage/images/kana_lock_on.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/kana_lock_on.png -------------------------------------------------------------------------------- /usage/images/kana_lock_on_small.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/kana_lock_on_small.png -------------------------------------------------------------------------------- /usage/images/machine.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/machine.png -------------------------------------------------------------------------------- /usage/images/machine_small.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/machine_small.png -------------------------------------------------------------------------------- /usage/images/mo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/mo.png -------------------------------------------------------------------------------- /usage/images/mo_small.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/mo_small.png -------------------------------------------------------------------------------- /usage/images/network.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/network.png -------------------------------------------------------------------------------- /usage/images/network_small.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/network_small.png -------------------------------------------------------------------------------- /usage/images/num_lock_off.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/num_lock_off.png -------------------------------------------------------------------------------- /usage/images/num_lock_off_small.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/num_lock_off_small.png -------------------------------------------------------------------------------- /usage/images/num_lock_on.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/num_lock_on.png -------------------------------------------------------------------------------- /usage/images/num_lock_on_small.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/num_lock_on_small.png -------------------------------------------------------------------------------- /usage/images/other_peripherals.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/other_peripherals.png -------------------------------------------------------------------------------- /usage/images/other_peripherals_small.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/other_peripherals_small.png -------------------------------------------------------------------------------- /usage/images/other_removable_devices.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/other_removable_devices.png -------------------------------------------------------------------------------- /usage/images/other_removable_devices_small.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/other_removable_devices_small.png -------------------------------------------------------------------------------- /usage/images/pause.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/pause.png -------------------------------------------------------------------------------- /usage/images/pause_small.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/pause_small.png -------------------------------------------------------------------------------- /usage/images/ports.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/ports.png -------------------------------------------------------------------------------- /usage/images/ports_small.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/ports_small.png -------------------------------------------------------------------------------- /usage/images/run.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/run.png -------------------------------------------------------------------------------- /usage/images/run_small.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/run_small.png -------------------------------------------------------------------------------- /usage/images/scroll_lock_off.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/scroll_lock_off.png -------------------------------------------------------------------------------- /usage/images/scroll_lock_off_small.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/scroll_lock_off_small.png -------------------------------------------------------------------------------- /usage/images/scroll_lock_on.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/scroll_lock_on.png -------------------------------------------------------------------------------- /usage/images/scroll_lock_on_small.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/scroll_lock_on_small.png -------------------------------------------------------------------------------- /usage/images/send_cad.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/send_cad.png -------------------------------------------------------------------------------- /usage/images/send_cad_small.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/send_cad_small.png -------------------------------------------------------------------------------- /usage/images/send_cae.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/send_cae.png -------------------------------------------------------------------------------- /usage/images/send_cae_small.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/send_cae_small.png -------------------------------------------------------------------------------- /usage/images/settings.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/settings.png -------------------------------------------------------------------------------- /usage/images/settings_small.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/settings_small.png -------------------------------------------------------------------------------- /usage/images/sound.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/sound.png -------------------------------------------------------------------------------- /usage/images/sound_small.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/sound_small.png -------------------------------------------------------------------------------- /usage/images/storage_controllers.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/storage_controllers.png -------------------------------------------------------------------------------- /usage/images/storage_controllers_small.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/storage_controllers_small.png -------------------------------------------------------------------------------- /usage/images/warning.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/warning.png -------------------------------------------------------------------------------- /usage/images/warning_small.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/warning_small.png -------------------------------------------------------------------------------- /usage/images/zip.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/zip.png -------------------------------------------------------------------------------- /usage/images/zip_small.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/86Box/docs/2542d356bccfc5f5646c31caea55c771ae81b49a/usage/images/zip_small.png -------------------------------------------------------------------------------- /usage/menubar.rst: -------------------------------------------------------------------------------- 1 | Menu bar 2 | ======== 3 | 4 | The menu bar located at the top of the 86Box window provides controls for the emulated machine as a whole, its display, and the 86Box user interface. 5 | 6 | .. important:: On macOS, the **Exit** (Quit), **Preferences** and **About 86Box** options are found in the **86Box** application menu instead of the locations outlined here. 7 | 8 | Action 9 | ------ 10 | 11 | * **Auto-pause on focus loss:** automatically pause emulation while the 86Box window is not focused. 12 | * **Keyboard requires capture:** require the mouse to be captured for keypresses to be forwarded to the emulated machine. Enabling this option allows the use of keyboard combinations (such as Alt+Tab) on the host system while the 86Box window is focused. 13 | * **Right CTRL is left ALT:** let the right Ctrl key act as a left Alt key, to simulate some special keyboards where the Alt key is located on the right side of the space bar. 14 | * **Pause:** pause emulation of the machine. Uncheck this option to resume emulation. You can alternatively press *Ctrl+Alt+F1* (:ref:`customizable `) to pause or resume emulation. 15 | * **Hard Reset:** force a reset of the emulated machine. Requires confirmation, which can be disabled by checking the *Don't show this message again* box. You can alternatively press *Ctrl+Alt+F12* (:ref:`customizable `) to hard reset. 16 | * **Ctrl+Alt+Del:** send a *Ctrl+Alt+Del* key combination to the emulated machine. You can alternatively press *Ctrl+F12* (:ref:`customizable `) to send that combination. 17 | * **Ctrl+Alt+Esc:** send a *Ctrl+Alt+Esc* key combination to the emulated machine. You can alternatively press *Ctrl+F10* (:ref:`customizable `) to send that combination. 18 | * **Exit:** quit 86Box. Requires confirmation, which can be disabled by checking the *Don't show this message again* box. 19 | 20 | View 21 | ---- 22 | 23 | * **Hide toolbar:** hides the :doc:`toolbar ` below the menu bar. 24 | * **Hide status bar:** hides the :doc:`status bar ` at the bottom of the window. 25 | * **Show non-primary monitors:** shows or hides the secondary display window if a :ref:`secondary video card ` is configured. 26 | * **Resizeable window:** allow the 86Box window to be freely resized. Unchecking this option will also return the window to its normal size. 27 | * **Remember size & position:** automatically save the size and position of the 86Box window to the emulated machine's configuration file. 28 | * **Renderer:** select a graphical renderer for the emulated display. 29 | 30 | * **Qt (Software)** is recommended in most cases. 31 | * **Qt (OpenGL)** and **Vulkan** are known to perform better on some host systems. Try these if your system is struggling to maintain 100% emulation speed. *Vulkan* may not be available if the host GPU is not Vulkan-capable. 32 | * **OpenGL (3.0 Core)** allows for shader effects to be applied to the emulated display, however, it is not compatible with older integrated GPUs. 33 | 34 | * **Renderer options:** open a window to configure the *OpenGL (3.0 Core)* renderer. This option will be available if that renderer is selected. 35 | 36 | * **Synchronize with video:** update the emulated display at its current refresh rate. 37 | * **Use target framerate:** update the emulated display at the selected refresh rate. 38 | * **VSync:** enable vertical sync. Recommended if tearing artifacts are observed. 39 | * **Add:** add a ``.glsl`` or ``.glslp`` file to the list of shaders to apply on the emulated display. 40 | * **Remove:** remove the selected shader from the list. 41 | * **Configure:** open a window to configure parameters on the selected shader. 42 | * **Move up/down:** move the selected shader up or down in the processing order. 43 | 44 | .. note:: 45 | * Many shaders are available for simulating CRT displays, VHS tapes and other aesthetics; the `RetroArch glsl-shaders repository `_ is a good place to start. 46 | * ``.cg`` and ``.cgp`` shaders are not supported, as these formats are long deprecated. 47 | 48 | * **Specify dimensions:** open a window where an exact size (in pixels) for the emulated display can be set. If checked, the *Lock to this size* box prevents changes in the emulated display's resolution from overriding the specified size. 49 | * **Force 4:3 display ratio:** stretch the emulated display to a 4:3 aspect ratio, independently of the emulated machine's screen resolution. 50 | * **Window scale factor:** scale the emulated display to half (*0.5x*), normal (*1x*), 50% larger (*1.5x*), double (*2x*) or larger (up to *8x*) sizes. 51 | * **Filter method:** select the filtering method (*Nearest* or *Linear*) to be used when scaling the emulated display. 52 | * **HiDPI scaling:** automatically scale the emulated display to real size if your host system has a HiDPI display. This option can be used alongside *Window scale factor* above. 53 | 54 | .. note:: If HiDPI scaling is disabled on a host with a HiDPI display, the emulated display's size may be off by one pixel due to an integer scaling limitation. 55 | 56 | * **Fullscreen:** enter full screen mode. You can press *Ctrl+Alt+Page Up* (:ref:`customizable `) to enter full screen mode or go back to windowed mode. 57 | * **Fullscreen stretch mode:** select the picture mode to use when in full screen mode. 58 | 59 | * **Full screen stretch:** stretch the emulated display to completely fill the host display. 60 | * **4:3:** stretch the emulated display to a 4:3 aspect ratio, then scale it to fit the host display. 61 | * **Square pixels (keep ratio):** scale the emulated display to fit the host display, without changing the aspect ratio. 62 | * **Integer scale:** scale the emulated display to the largest integer scale factor to fit the host display. This provides the highest possible picture quality, at the cost of black bars if the host display's resolution is not divisible by the emulated display's resolution. 63 | * **4:3 integer scale:** stretch the emulated display to a 4:3 aspect ratio, then scale it to the largest integer scale factor to fit the host display. 64 | 65 | * **Apply fullscreen stretch mode when maximized:** apply the picture mode selected above in windowed mode if *Resizeable window* is enabled and the window is maximized. 66 | * **EGA/(S)VGA settings:** contains display settings specific to EGA, VGA and Super VGA video hardware. 67 | 68 | * **Inverted VGA monitor:** emulate a VGA monitor with inverted colors. 69 | * **VGA screen type:** select the VGA monitor type to emulate. *Color*, *Grayscale*, *Amber*, *Green* and *White* phosphor monitors can be selected. 70 | * **Grayscale conversion type:** select the color-to-grayscale conversion profile (*BT.601*, *BT.709* or *Average*) to use when a grayscale monitor is selected. 71 | 72 | * **CGA/PCjr/Tandy/EGA/(S)VGA overscan:** add an overscan border around the display. This border is only added when emulating the specified video hardware types. 73 | * **Change contrast for monochrome display:** optimize the contrast of monochrome CGA monitors for 4-color operation. 74 | 75 | Media 76 | ----- 77 | 78 | This menu lists all storage drives and network cards attached to the emulated machine, and provides the same options that are accessible by clicking the respective device's icon on the :doc:`status bar `. 79 | 80 | The **Clear image history** option empties the list of recently-loaded images on all storage drives. 81 | 82 | Tools 83 | ----- 84 | 85 | * **Settings:** open the :doc:`Settings <../settings/index>` window to configure the emulated machine. 86 | * **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. 87 | * **Enable Discord integration:** enable Discord Rich Presence. 86Box shares the emulated machine's name, model and CPU with other Discord users. 88 | 89 | .. 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. 90 | 91 | * **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. 92 | * **Sound:** provides the same options that are accessible by clicking the :ref:`sound icon on the status bar `. 93 | * **Preferences:** open the *Preferences* window, which provides the following options: 94 | 95 | * **Language:** select a language for the 86Box user interface. 96 | * **Mouse sensitivity:** adjust the emulated mouse's tracking sensitivity. 97 | * **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. 98 | * **Inhibit multimedia keys on Windows:** if checked, multimedia keys such as **Volume Up/Down** will not be passed through to the emulated machine. This option is only available on Windows. 99 | * **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. 100 | 101 | * **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. 102 | * **Open screenshots folder**: open the host system's file browser on the directory where screenshots of this emulated machine are saved. 103 | 104 | Help 105 | ---- 106 | 107 | * **Documentation:** open the very documentation you're reading. 108 | * **About 86Box:** show credits, license and build information about 86Box. 109 | -------------------------------------------------------------------------------- /usage/roms.rst: -------------------------------------------------------------------------------- 1 | ROM set 2 | ======= 3 | 4 | 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. 5 | 6 | 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. 7 | 8 | .. note:: The expected file names of the ROM dumps and their locations within the set are hardcoded in the emulator. If you rename them or add your own dumps with different file names, the emulator will not be able to make use of them. 9 | 10 | Search path 11 | ----------- 12 | 13 | The emulator utilizes a search path mechanism to locate ROMs. By default, the following locations are considered: 14 | 15 | 1. ``roms`` subdirectory in the VM path 16 | 2. ``roms`` subdirectory in the same directory as the emulator executable 17 | 3. Platform-specific locations 18 | 19 | A custom location can be specified by using the ``-R`` or ``--rompath`` command line argument, which then precedes any other considered locations. 20 | 21 | .. rubric:: Windows 22 | 23 | The following locations are searched on Windows: 24 | 25 | 1. ``%LOCALAPPDATA%\86Box\roms`` 26 | 2. ``%PROGRAMDATA%\86Box\roms`` 27 | 28 | .. rubric:: Unix 29 | 30 | 86Box honors the XDG base directory specification on Linux and other Unix-compatible platforms. The following locations are searched: 31 | 32 | 1. ``$XDG_DATA_HOME/86Box/roms`` 33 | 2. ``86Box/roms`` subdirectory in each path listed in ``$XDG_DATA_DIRS`` 34 | 35 | This usually resolves to ``~/.local/share/86Box/roms``, ``/usr/local/share/86Box/roms`` and ``/usr/share/86Box/roms`` (in order). 36 | 37 | .. rubric:: macOS 38 | 39 | The following locations are searched on macOS: 40 | 41 | 1. ``~/Library/Application Support/net.86box.86Box/roms`` 42 | 2. ``/Library/Application Support/net.86box.86Box/roms`` 43 | 44 | .. tip:: The list of all paths searched when loading ROMs is printed to the log and standard output when 86Box starts. 45 | -------------------------------------------------------------------------------- /usage/statusbar.rst: -------------------------------------------------------------------------------- 1 | .. include:: /include.rst 2 | 3 | Status bar 4 | ========== 5 | 6 | The status bar located at the bottom of the 86Box window provides icons related to devices attached to the emulated machine. Move your mouse cursor over an icon to see what device it represents. **Most icons can be clicked on** to access options related to their respective devices, which are listed below, and image files can be dropped on the icons for removable media devices such as floppy and CD-ROM drives. Additionally, green or red indicator lights will appear on an icon when its device is in use, denoting reads and writes respectively, unless :ref:`Update status bar icons ` is disabled. 7 | 8 | |cassette| Cassette deck 9 | ------------------------ 10 | 11 | A cassette tape icon will appear if :ref:`IBM cassette emulation ` is enabled. 12 | 13 | * **New image:** create a new cassette tape image file. 14 | * **Existing image:** insert a :ref:`cassette tape image file ` into the deck. Dragging and dropping an image file on the icon will also load it. 15 | * **Existing image (Write-protected):** insert a cassette tape image file into the deck as a read-only tape. 16 | * A history of the last few images that were loaded into the deck. Click on an entry to load it back. 17 | * **Record:** start recording data to the cassette tape. Not available if the tape is read-only. 18 | * **Play:** start playing the cassette tape. 19 | * **Rewind to the beginning:** rewind the cassette tape to its beginning. 20 | * **Fast forward to the end:** fast forward the cassette tape to its end. 21 | * **Eject:** remove the currently-inserted cassette tape from the deck. 22 | 23 | |cartridge| PCjr cartridges 24 | --------------------------- 25 | 26 | Two cartridge icons will appear if the **IBM PCjr** is being emulated. Each icon corresponds to a cartridge slot on the PCjr's front panel. 27 | 28 | * **Image:** insert a :ref:`cartridge image file ` into this slot. Inserting a cartridge will reset the PCjr. Dragging and dropping an image file on the icon will also load it. 29 | * A history of the last few images that were loaded into this slot. Click on an entry to load it back. 30 | * **Eject:** remove the currently-inserted cartridge from this slot. 31 | 32 | |floppy_35| |floppy_525| Floppy drives 33 | -------------------------------------- 34 | 35 | A 3.5" or 5.25" floppy icon will appear for each configured :ref:`floppy drive `. 36 | 37 | * **New image:** create a new disk image file. Opens the *New Image* window, which lets you select the image size and where to save the file. 38 | * **Existing image:** insert a :ref:`disk image file ` into this drive. Dragging and dropping an image file on the icon will also load it. 39 | * **Existing image (Write-protected):** insert a disk image file into this drive as a read-only disk. 40 | * A history of the last few images that were loaded into this drive. Click on an entry to load it back. 41 | * **Export to 86F:** convert the currently-inserted disk image file to 86Box's :doc:`../dev/formats/86f` surface image format. You will be asked where to save the converted file. 42 | * **Eject:** remove the currently-inserted disk from this drive. 43 | 44 | |cdrom| CD-ROM drives 45 | --------------------- 46 | 47 | A CD icon will appear for each configured :ref:`CD-ROM drive `. 48 | 49 | * **Mute:** mute any :ref:`hardware/diskimages:CD audio` played through this drive's analog output. CD audio is unmuted by default on the first configured CD-ROM drive. 50 | * **Image:** insert a :ref:`CD-ROM or DVD-ROM disc image file ` into this drive. Dragging and dropping an image file on the icon will also load it. 51 | * **Folder:** insert a virtual CD-ROM or DVD-ROM with the contents of a host folder into this drive. Dragging and dropping a folder on the icon will also load it. 52 | * A history of the last few images, folders or host drives that were loaded into this drive. Click on an entry to load it back. 53 | * A list of host CD-ROM or DVD-ROM drives available for passthrough. Click on an entry to attach it to the emulated drive. 54 | * **Eject:** remove any disc inserted into this drive, or detach a host drive. 55 | 56 | |zip| |mo| ZIP and MO drives 57 | ---------------------------- 58 | 59 | A ZIP or MO icon will appear for each configured :doc:`additional removable storage drive <../settings/removable>`. 60 | 61 | * **New image:** create a new disk image file. Opens the *New Image* window, which lets you select the image size and where to save the file. 62 | * **Existing image:** insert a :ref:`disk image file ` into this drive. Dragging and dropping an image file on the icon will also load it. 63 | * **Existing image (Write-protected):** insert a disk image file into this drive as a read-only disk. 64 | * A history of the last few images that were loaded into this drive. Click on an entry to load it back. 65 | * **Eject:** remove the currently-inserted disk from this drive. 66 | 67 | |hard_disk| Hard disks 68 | ---------------------- 69 | 70 | A hard disk icon will appear for each configured :doc:`hard disk bus <../settings/hdd>`. For example, if you have both IDE and SCSI hard disks configured, two hard disk icons will appear: one representing all IDE disks, and another one representing all SCSI disks. No options are available. 71 | 72 | |network| Network 73 | ----------------- 74 | 75 | A network icon will appear for each configured :doc:`network card <../settings/network>`. 76 | 77 | * **Connected:** connect this card to its network. Network cards with link state detection support will report a disconnected cable if this option is unchecked. 78 | 79 | |sound| Sound 80 | ------------- 81 | 82 | This icon is always present, providing options to control all audio produced by the emulated machine's PC speaker, :doc:`sound cards <../settings/sound>` and other sound hardware. 83 | 84 | * **Mute:** mute all audio. You can alternatively press *Ctrl+Alt+M* (:ref:`customizable `) to mute or unmute audio. 85 | * **Sound gain:** open a gain control, which allows for increasing the loudness of all audio. 86 | 87 | .. note:: Sound options do not apply to MIDI music sent to a software synthesizer through the :ref:`System MIDI ` device, as these synthesizers are external to 86Box. 88 | 89 | Additional information area 90 | --------------------------- 91 | 92 | This area, located to the right of the icons described above, contains additional information which may be provided by components such as the :ref:`settings/peripherals:ISABugger` and :ref:`settings/peripherals:POST card`. 93 | 94 | Monitor sleep mode 95 | ^^^^^^^^^^^^^^^^^^ 96 | 97 | The *Monitor in sleep mode* message will be displayed if the emulated monitor has been put into DPMS sleep mode by the operating system. Pressing a key or moving the mouse is often enough to wake the monitor up. 98 | 99 | MT-32 display 100 | ^^^^^^^^^^^^^ 101 | 102 | Any text messages sent to the LCD screen of an :ref:`emulated Roland MT-32/CM-32L synthesizer ` are displayed here. 103 | 104 | ISABugger 105 | ^^^^^^^^^ 106 | 107 | The ISABugger's hexadecimal displays and LED banks are displayed here. See :doc:`../hardware/isabugger` for more information. 108 | 109 | POST card 110 | ^^^^^^^^^ 111 | 112 | 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. 113 | 114 | .. note:: The additional information area can only be used by one component at a time. The MT-32 display has the highest priority, followed by the monitor sleep mode message, then the ISABugger and POST card with the same priority (taking over whenever they're written to). 115 | 116 | |num_lock_off| |caps_lock_off| |scroll_lock_off| Keyboard indicators 117 | -------------------------------------------------------------------- 118 | 119 | Indicator lights for |num_lock_off_small| Num Lock, |caps_lock_off_small| Caps Lock and |scroll_lock_off_small| Scroll Lock on the emulated keyboard are displayed on the right side of the status bar. 120 | 121 | A |kana_lock_off_small| Kana Lock indicator is also displayed when emulating a machine with a Japanese AX keyboard. 122 | -------------------------------------------------------------------------------- /usage/toolbar.rst: -------------------------------------------------------------------------------- 1 | .. include:: /include.rst 2 | 3 | Toolbar 4 | ======= 5 | 6 | The toolbar located at the top of the 86Box window (right below the :doc:`menu bar `) has two purposes: it provides quick actions for the emulated machine on its left hand side, and displays status information on its right hand side. 7 | 8 | |pause| |run| Pause/resume execution 9 | ------------------------------------ 10 | 11 | Pause emulation of the machine. Press again to resume emulation. You can alternatively press *Ctrl+Alt+F1* (:ref:`customizable `) to pause or resume emulation. 12 | 13 | .. note:: Emulation is automatically paused when the emulated machine enters ACPI sleep mode. 14 | 15 | |hard_reset| Hard reset 16 | ----------------------- 17 | 18 | Force a reset of the emulated machine. Requires confirmation, which can be disabled by checking the *Don't show this message again* box. You can alternatively press *Ctrl+Alt+F12* (:ref:`customizable `) to hard reset. 19 | 20 | |acpi_shutdown| ACPI shutdown 21 | ----------------------------- 22 | 23 | Send a power button press to the emulated machine. Only available on machines with ACPI soft power off support. 24 | 25 | |send_cad| |send_cae| Press Ctrl+Alt+Del/Ctrl+Alt+Esc 26 | ------------------------------------------------------- 27 | 28 | Send a *Ctrl+Alt+Del* (left-most icon) or *Ctrl+Alt+Esc* (right-most icon) key combination to the emulated machine. You can alternatively press *Ctrl+F12* to send a *Ctrl+Alt+Del* combination, or *Ctrl+F10* to send *Ctrl+Alt+Esc*; both key combinations are :ref:`customizable `. 29 | 30 | |settings| Settings 31 | ------------------- 32 | 33 | Open the :doc:`Settings <../settings/index>` window to configure the emulated machine. 34 | 35 | Status area 36 | ----------- 37 | 38 | The right hand side of the toolbar displays status information, such as: 39 | 40 | * **Emulation speed** in percentage. If this number stays consistently below 100%, your host system is not keeping up with emulating the configured hardware. 41 | * **Mouse state** (captured or released) if a :ref:`mouse ` is enabled. 42 | * **Pause indicator** if emulation is paused. 43 | --------------------------------------------------------------------------------