.. include:: /include.rst Devices ======= The **device** is the main unit of emulated components in 86Box. Each device has one or more ``device_t`` structures, which contain metadata about the device itself, several callbacks and an array of user-facing configuration options. Unless otherwise stated, all structures and functions in this page are provided by ``86box/device.h``. .. flat-table:: device_t :header-rows: 1 :widths: 1 1 999 * - :cspan:`1` Member - Description * - :cspan:`1` name - The device's name, displayed in the user interface. ``"Foo-1234"`` for example. Suffixes like ``"(PCI)"`` are removed at run-time. * - :cspan:`1` internal_name - The device's internal name, used to identify the device in the emulated machine's configuration file. ``"foo1234"`` for example. * - :cspan:`1` flags - One or more bitwise flags to indicate the expansion bus(es) supported by the device, for determining device eligibility on the selected machine: * ``DEVICE_ISA``: 8-bit ISA; * ``DEVICE_AT``: 16-bit ISA; * ``DEVICE_EISA``: EISA (reserved for future use); * ``DEVICE_VLB``: VESA Local Bus; * ``DEVICE_PCI``: 32-bit PCI; * ``DEVICE_AGP``: AGP 3.3V; * ``DEVICE_AC97``: AMR or CNR; * ``DEVICE_PCJR``: IBM PCjr; * ``DEVICE_PS2``: IBM PS/1 or PS/2; * ``DEVICE_MCA``: IBM Micro Channel Architecture; * ``DEVICE_CBUS``: PC-98 C-BUS (reserved for future use); * ``DEVICE_COM``: serial (reserved for future use); * ``DEVICE_LPT``: parallel (reserved for future use). * - :cspan:`1` local - 32-bit value which can be read from this structure by the ``init`` callback. Use this value to tell different subtypes of the same device, for example. * - :cspan:`1` init - Function called whenever this device is initialized, either from starting 86Box or from a hard reset. Can be ``NULL``. Takes the form of: ``void *init(const struct device_t *info)`` where ``info`` is a pointer to this ``device_t`` structure, and the return value is an opaque pointer passed to the other callbacks below, usually a :ref:`state structure `. The opaque pointer will be invalid if this function is ``NULL``. * - :cspan:`1` close - Function called whenever this device is de-initialized, either from closing 86Box or from a hard reset. Can be ``NULL``. Takes the form of: ``void close(void *priv)`` where ``priv`` is the opaque pointer that was returned by ``init``. * - :cspan:`1` reset - Function called whenever this device undergoes a soft reset. Can be ``NULL``. Takes the form of: ``void reset(void *priv)`` where ``priv`` is the opaque pointer that was returned by ``init``. * - :rspan:`2` .. raw:: html
union
- available - Function called whenever this device's availability is being checked. Can be ``NULL``. Takes the form of: ``int available()`` where the return value must be ``1`` if the device is available for selection, or ``0`` if it is unavailable (due to missing ROMs, for example). The device will always be available if this function is ``NULL``. * - poll - Function called whenever the mouse position is updated. Valid for mouse devices only. Takes the form of: ``int poll(int x, int y, int z, int b, void *priv)`` where ``x`` and ``y`` are the relative movement coordinates, ``z`` is the relative wheel coordinate, ``b`` is the button state (bit 0 / 0x01 set for left button, bit 1 / 0x02 set for right button, bit 3 / 0x04 set for middle button), ``priv`` is the opaque pointer that was returned by ``init``, and the return value must be ``0`` if the change was processed or any other value otherwise. * - register_pci_slot - Reserved for future use. * - :cspan:`1` speed_changed - Function called whenever the emulated CPU clock speed is changed. Can be ``NULL``. Timer intervals and anything else sensitive to the CPU clock speed should be updated in this callback. Takes the form of: ``void speed_changed(void *priv)`` where ``priv`` is the opaque pointer that was returned by ``init``. * - :cspan:`1` force_redraw - Function called whenever the emulated screen has to be fully redrawn. Can be ``NULL``. Only useful for video cards. Takes the form of: ``void force_redraw(void *priv)`` where ``priv`` is the opaque pointer that was returned by ``init``. * - :cspan:`1` config - Array of device configuration options, or ``NULL`` if no options are available. See :ref:`dev/api/device:Configuration`. State structure --------------- Most devices need a place to store their internal state. We discourage the use of global structures, and instead recommend allocating state structures dynamically in the ``init`` callback and freeing them in the ``close`` callback:: typedef struct { uint32_t type; /* example: copied from device_t.local */ uint8_t regs[256]; /* example: 256*8-bit registers */ } foo_t; static void * foo_init(const device_t *info) { /* Allocate a blank state structure. */ foo_t *dev = (foo_t *) malloc(sizeof(foo_t)); memset(dev, 0, sizeof(foo_t)); /* Do whatever you want. */ dev->type = info->local; /* copy device_t.local value */ /* Return a pointer to the state structure. */ return dev; } static void foo_close(void *priv) { /* Get the state structure. */ foo_t *dev = (foo_t *) priv; /* Do whatever you want, then deallocate the state structure. */ free(dev); } const device_t foo1234_device = { .name = "Foo-1234", .internal_name = "foo1234", .flags = DEVICE_AT, /* 16-bit ISA */ .local = 1234, .init = foo_init, .close = foo_close, /* ... */ }; const device_t foo4321_device = { .name = "Foo-4321", .internal_name = "foo4321", .flags = DEVICE_PCI, /* 32-bit PCI */ .local = 4321, /* different device subtype */ .init = foo_init, .close = foo_close, /* ... */ }; Configuration ------------- 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. Examples for all option types currently configurable through the user interface are shown in the image below. .. image:: images/deviceconfig.png :align: center These options are stored in the emulated machine's configuration file, in a section identified by the device's ``name``: .. code-block:: none [Foo-1234] selection = 0 hex16 = 0220 hex20 = D8000 fname = D:/VMs/86Box/86Box.exe binary = 1 spinner = 1234 midi_out = 0 midi_in = 0 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`` ``-1``. .. flat-table:: device_config_t :header-rows: 1 :widths: 1 999 * - Member - Description * - name - Internal name for this option, used in the emulated machine's configuration file. * - description - Description for this option, displayed in the user interface. * - type - One of the following option types: * ``CONFIG_SELECTION``: combobox containing a list of values specified by the ``selection`` member; * ``CONFIG_HEX16``: combobox containing a list of 16-bit hexadecimal values (useful for ISA I/O ports) specified by the ``selection`` member; * ``CONFIG_HEX20``: combobox containing a list of 20-bit hexadecimal values (useful for ISA memory addresses) specified by the ``selection`` member; * ``CONFIG_STRING``: arbitrary text string entered by the user, currently **not visible nor configurable** in the user interface; * ``CONFIG_FNAME``: arbitrary file path entered by the user directly or through a file selector button; * ``CONFIG_BINARY``: checkbox; * ``CONFIG_INT``: arbitrary integer number, currently **not visible nor configurable** in the user interface; * ``CONFIG_SPINNER``: arbitrary integer number entered by the user directly or through up/down arrows, within a range specified by the ``spinner`` member; * ``CONFIG_MAC``: last 3 octets of a MAC address, currently **not visible nor configurable** in the user interface; * ``CONFIG_MIDI_OUT``: combobox containing a list of system MIDI output devices; * ``CONFIG_MIDI_IN``: combobox containing a list of system MIDI input devices; * ``-1``: **mandatory** terminator to indicate the end of the option list. * - default_string - Default string value for a ``CONFIG_STRING`` option. Can be ``""`` if not applicable. * - default_int - Default integer value for a ``CONFIG_HEX16``, ``CONFIG_HEX20``, ``CONFIG_INT`` or ``CONFIG_SPINNER`` option. Can be 0 if not applicable. * - file_filter - 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: ``"Raw image (*.img)|*.img|Virtual Hard Disk (*.vhd)|*.vhd"`` * - spinner - ``device_config_spinner_t`` sub-structure containing the minimum/maximum/step values for a ``CONFIG_SPINNER`` option. Can be ``{ 0 }`` if not applicable. .. flat-table:: :header-rows: 1 :widths: 1 999 * - Member - Description * - min - Minimum selectable value. * - max - Maximum selectable value. * - step - 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``. * - selection - 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 ``""``. .. flat-table:: :header-rows: 1 :widths: 1 999 * - Member - Description * - description - Description for this choice, displayed in the user interface. * - value - Integer value corresponding to this choice, used in the emulated machine's configuration file. Configured option values can be accessed using ``device_get_config_*`` functions from within the device's ``init`` callback. .. 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 your device's :ref:`state structure ` if necessary. .. flat-table:: device_get_config_string :header-rows: 1 :widths: 1 999 * - Parameter - Description * - name - The option's ``name``. Accepted option types are ``CONFIG_STRING`` and ``CONFIG_FNAME``. * - **Return value** - The option's configured string value, or its ``default_string`` if no value is present. Note that a ``const char *`` is returned. .. flat-table:: device_get_config_int / device_get_config_hex16 / device_get_config_hex20 :header-rows: 1 :widths: 1 999 * - Parameter - Description * - name - The option's ``name``. Accepted option types are: * ``device_get_config_int``: ``CONFIG_SELECTION``, ``CONFIG_BINARY``, ``CONFIG_INT``, ``CONFIG_SPINNER``, ``CONFIG_MIDI_OUT``, ``CONFIG_MIDI_IN`` * ``device_get_config_hex16``: ``CONFIG_HEX16`` * ``device_get_config_hex20``: ``CONFIG_HEX20`` * - **Return value** - The option's configured integer value (``CONFIG_BINARY`` returns 1 if checked or 0 otherwise), or its ``default_int`` if no value is present. .. flat-table:: device_get_config_int_ex / device_get_config_mac :header-rows: 1 :widths: 1 999 * - Parameter - Description * - name - The option's ``name``. Accepted option types are: * ``device_get_config_int_ex``: ``CONFIG_SELECTION``, ``CONFIG_BINARY``, ``CONFIG_INT``, ``CONFIG_SPINNER``, ``CONFIG_MIDI_OUT``, ``CONFIG_MIDI_IN`` * ``device_get_config_mac``: ``CONFIG_MAC`` * - dflt_int - The default value to return if no configured value is present. * - **Return value** - The option's configured integer value (``CONFIG_BINARY`` returns 1 if checked or 0 otherwise), or ``dflt_int`` if no value is present.