diff --git a/dev/api/device.rst b/dev/api/device.rst index 3f3ec65..1c512d0 100644 --- a/dev/api/device.rst +++ b/dev/api/device.rst @@ -105,13 +105,13 @@ The **device** is the main unit of emulated components in 86Box. Each device is 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: +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. .. container:: toggle .. container:: toggle-header - Code example: allocating and freeing a state structure + Code example: allocating and deallocating a state structure .. code-block:: @@ -192,7 +192,7 @@ A device will be **available** for selection by the user if these criteria are m 2. The selected machine has any of the expansion buses specified in the device's ``flags``; 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``). -The ``available`` callback can be used to verify the presence of ROM files if any ROMs are required by the device: +The ``available`` callback can be used to verify the presence of ROM files if any ROMs are required by the device. .. container:: toggle @@ -220,11 +220,13 @@ The ``available`` callback can be used to verify the presence of ROM files if an 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. [TO BE UPDATED ONCE I GET OUT OF HIDPI] +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: -.. image:: images/deviceconfig.png +.. figure:: images/deviceconfig.png :align: center + All option types currently configurable through the user interface. [TO BE UPDATED ONCE I GET OUT OF HIDPI] + These options are stored in the emulated machine's configuration file, in a section identified by the device's ``name``: .. code-block:: none @@ -240,7 +242,7 @@ These options are stored in the emulated machine's configuration file, in a sect 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``: +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``. .. container:: toggle diff --git a/dev/api/pci.rst b/dev/api/pci.rst index cb02a63..527f7d5 100644 --- a/dev/api/pci.rst +++ b/dev/api/pci.rst @@ -22,7 +22,7 @@ PCI devices can be added with the ``pci_add_card`` function in the device's ``in #define FOO_ONBOARD 0x80000000 /* most significant bit set = on-board */ typedef struct { - uint8_t pci_regs[256]; + uint8_t pci_regs[256]; /* 256*8-bit configuration register array */ int slot; } foo_t; @@ -259,7 +259,7 @@ The most important registers in the standard set are: Multi-function devices ---------------------- -PCI defines the concept of **functions**, which allow a physical device to contain up to 8 sub-devices (numbered from ``0`` to ``7``), each one with their own configuration space and set of resources controlled by :ref:`dev/api/pci:Base Address Registers`. Most (but not all) multi-function devices are chipset southbridges, which may implement a function for the PCI-ISA bridge, another one for the IDE controller, one or more for USB and so on. +PCI defines the concept of **functions**, which allow a physical device to contain up to 8 sub-devices (numbered from ``0`` to ``7``), each with their **own configuration space**, and their **own resources** controlled by :ref:`dev/api/pci:Base Address Registers`. Most (but not all) multi-function PCI devices are chipset southbridges, which may implement a function for the PCI-ISA bridge (and general configuration), another one for the IDE controller, one or more for USB and so on. The ``func`` parameter passed to a device's configuration space read/write callbacks provides the **function number** for which the configuration space is being accessed. There are two main requirements for implementing multi-function devices: @@ -276,7 +276,8 @@ The ``func`` parameter passed to a device's configuration space read/write callb .. code-block:: typedef struct { - uint8_t pci_regs[2][256]; /* two 256*8-bit register arrays, one for each function */ + uint8_t pci_regs[2][256]; /* two 256*8-bit configuration register arrays, + one for each function */ } foo_t; static uint8_t @@ -773,7 +774,7 @@ The main difference between this register and BARs is that the ROM can be enable } static int - foo_available() + foo4321_available() { /* This device can only be used if its ROM is present. */ return rom_present("roms/scsi/foo/foo4321.bin"); @@ -800,7 +801,7 @@ The main difference between this register and BARs is that the ROM can be enable /* ... */ .init = foo_init, .reset = foo_reset, - { .available = foo_available }, + { .available = foo4321_available }, /* ... */ };