More API stuff

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
 

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 },
             /* ... */
         };