Index: /trunk/src/VBox/Devices/Bus/DevPCI.cpp
===================================================================
--- /trunk/src/VBox/Devices/Bus/DevPCI.cpp	(revision 44794)
+++ /trunk/src/VBox/Devices/Bus/DevPCI.cpp	(revision 44795)
@@ -179,7 +179,7 @@
 /** Converts a bus instance pointer to a device instance pointer. */
 #define PCIBUS_2_DEVINS(pPciBus)        ((pPciBus)->CTX_SUFF(pDevIns))
-/** Converts a device instance pointer to a PCIGLOBALS pointer. */
+/** Converts a PCI bus device instance pointer to a PCIGLOBALS pointer. */
 #define DEVINS_2_PCIGLOBALS(pDevIns)    ((PPCIGLOBALS)(PDMINS_2_DATA(pDevIns, PPCIGLOBALS)))
-/** Converts a device instance pointer to a PCIBUS pointer. */
+/** Converts a PCI bus device instance pointer to a PCIBUS pointer. */
 #define DEVINS_2_PCIBUS(pDevIns)        ((PPCIBUS)(&PDMINS_2_DATA(pDevIns, PPCIGLOBALS)->PciBus))
 
@@ -187,5 +187,5 @@
  *  @note This works only if the bus number is 0!!!
  */
-#define PCIBUS_2_PCIGLOBALS(pPciBus)    ( (PPCIGLOBALS)((uintptr_t)(pPciBus) - RT_OFFSETOF(PCIGLOBALS, PciBus)) )
+#define PCIBUS_2_PCIGLOBALS(pPciBus)    RT_FROM_MEMBER(pPciBus, PCIGLOBALS, PciBus)
 
 /** @def PCI_LOCK
@@ -743,12 +743,7 @@
 }
 
-/**
- * Set the IRQ for a PCI device on the host bus.
- *
- * @param   pDevIns         Device instance of the PCI Bus.
- * @param   pPciDev         The PCI device structure.
- * @param   iIrq            IRQ number to set.
- * @param   iLevel          IRQ level.
- * @param   uTagSrc         The IRQ tag and source ID (for tracing).
+
+/**
+ * @interface_method_impl{PDMPCIBUSREG,pfnSetIrq}
  */
 PDMBOTHCBDECL(void) pciSetIrq(PPDMDEVINS pDevIns, PPCIDEVICE pPciDev, int iIrq, int iLevel, uint32_t uTagSrc)
@@ -1125,16 +1120,9 @@
 #endif /* IN_RING3 */
 
-/* -=-=-=-=-=- wrappers -=-=-=-=-=- */
-
-/**
- * Port I/O Handler for PCI address OUT operations.
- *
- * @returns VBox status code.
- *
- * @param   pDevIns     The device instance.
- * @param   pvUser      User argument - ignored.
- * @param   uPort       Port number used for the IN operation.
- * @param   u32         The value to output.
- * @param   cb          The value size in bytes.
+
+/* -=-=-=-=-=- I/O ports -=-=-=-=-=- */
+
+/**
+ * @callback_method_impl{FNIOMIOPORTOUT, PCI address}
  */
 PDMBOTHCBDECL(int) pciIOPortAddressWrite(PPDMDEVINS pDevIns, void *pvUser, RTIOPORT Port, uint32_t u32, unsigned cb)
@@ -1156,13 +1144,5 @@
 
 /**
- * Port I/O Handler for PCI address IN operations.
- *
- * @returns VBox status code.
- *
- * @param   pDevIns     The device instance.
- * @param   pvUser      User argument - ignored.
- * @param   uPort       Port number used for the IN operation.
- * @param   pu32        Where to store the result.
- * @param   cb          Number of bytes read.
+ * @callback_method_impl{FNIOMIOPORTIN, PCI address}
  */
 PDMBOTHCBDECL(int) pciIOPortAddressRead(PPDMDEVINS pDevIns, void *pvUser, RTIOPORT Port, uint32_t *pu32, unsigned cb)
@@ -1186,13 +1166,5 @@
 
 /**
- * Port I/O Handler for PCI data OUT operations.
- *
- * @returns VBox status code.
- *
- * @param   pDevIns     The device instance.
- * @param   pvUser      User argument - ignored.
- * @param   uPort       Port number used for the IN operation.
- * @param   u32         The value to output.
- * @param   cb          The value size in bytes.
+ * @callback_method_impl{FNIOMIOPORTOUT, PCI data}
  */
 PDMBOTHCBDECL(int) pciIOPortDataWrite(PPDMDEVINS pDevIns, void *pvUser, RTIOPORT Port, uint32_t u32, unsigned cb)
@@ -1214,13 +1186,5 @@
 
 /**
- * Port I/O Handler for PCI data IN operations.
- *
- * @returns VBox status code.
- *
- * @param   pDevIns     The device instance.
- * @param   pvUser      User argument - ignored.
- * @param   uPort       Port number used for the IN operation.
- * @param   pu32        Where to store the result.
- * @param   cb          Number of bytes read.
+ * @callback_method_impl{FNIOMIOPORTIN, PCI data}
  */
 PDMBOTHCBDECL(int) pciIOPortDataRead(PPDMDEVINS pDevIns, void *pvUser, RTIOPORT Port, uint32_t *pu32, unsigned cb)
@@ -1241,4 +1205,6 @@
 #ifdef IN_RING3
 
+/* -=-=-=-=-=- Saved state -=-=-=-=-=- */
+
 /**
  * Common worker for pciR3SaveExec and pcibridgeR3SaveExec.
@@ -1271,10 +1237,5 @@
 
 /**
- * Saves a state of the PCI device.
- *
- * @returns VBox status code.
- * @param   pDevIns     The device instance.
- * @param   pPciDev     Pointer to PCI device.
- * @param   pSSM  The handle to save the state to.
+ * @callback_method_impl{FNSSMDEVSAVEEXEC}
  */
 static DECLCALLBACK(int) pciR3SaveExec(PPDMDEVINS pDevIns, PSSMHANDLE pSSM)
@@ -1593,11 +1554,5 @@
 
 /**
- * Loads a saved PCI device state.
- *
- * @returns VBox status code.
- * @param   pDevIns     The device instance.
- * @param   pSSM        The handle to the saved state.
- * @param   uVersion    The data unit version number.
- * @param   uPass       The data pass.
+ * @callback_method_impl{FNSSMDEVLOADEXEC}
  */
 static DECLCALLBACK(int) pciR3LoadExec(PPDMDEVINS pDevIns, PSSMHANDLE pSSM, uint32_t uVersion, uint32_t uPass)
@@ -1648,5 +1603,5 @@
 
 
-/* -=-=-=-=-=- real code -=-=-=-=-=- */
+/* -=-=-=-=-=- PCI Bus Interface Methods (PDMPCIBUSREG) -=-=-=-=-=- */
 
 /**
@@ -1791,13 +1746,5 @@
 
 /**
- * Registers the device with the default PCI bus.
- *
- * @returns VBox status code.
- * @param   pDevIns         Device instance of the PCI Bus.
- * @param   pPciDev         The PCI device structure.
- *                          Any PCI enabled device must keep this in it's instance data!
- *                          Fill in the PCI data config before registration, please.
- * @param   pszName         Pointer to device name (permanent, readonly). For debugging, not unique.
- * @param   iDev            The PCI device number. Use a negative value for auto assigning one.
+ * @interface_method_impl{PDMPCIBUSREG,pfnRegister}
  */
 static DECLCALLBACK(int) pciR3Register(PPDMDEVINS pDevIns, PPCIDEVICE pPciDev, const char *pszName, int iDev)
@@ -1824,4 +1771,7 @@
 
 
+/**
+ * @interface_method_impl{PDMPCIBUSREG,pfnIORegionRegisterR3}
+ */
 static DECLCALLBACK(int) pciR3CommonIORegionRegister(PPDMDEVINS pDevIns, PPCIDEVICE pPciDev, int iRegion, uint32_t cbRegion,
                                                      PCIADDRESSSPACE enmType, PFNPCIIOREGIONMAP pfnCallback)
@@ -1866,8 +1816,9 @@
 
 /**
- * @copydoc PDMPCIBUSREG::pfnSetConfigCallbacksR3
- */
-static DECLCALLBACK(void) pciR3CommonSetConfigCallbacks(PPDMDEVINS pDevIns, PPCIDEVICE pPciDev, PFNPCICONFIGREAD pfnRead, PPFNPCICONFIGREAD ppfnReadOld,
-                                                        PFNPCICONFIGWRITE pfnWrite, PPFNPCICONFIGWRITE ppfnWriteOld)
+ * @interface_method_impl{PDMPCIBUSREG,pfnSetConfigCallbacksR3}
+ */
+static DECLCALLBACK(void)
+pciR3CommonSetConfigCallbacks(PPDMDEVINS pDevIns, PPCIDEVICE pPciDev, PFNPCICONFIGREAD pfnRead, PPFNPCICONFIGREAD ppfnReadOld,
+                              PFNPCICONFIGWRITE pfnWrite, PPFNPCICONFIGWRITE ppfnWriteOld)
 {
     NOREF(pDevIns);
@@ -1884,8 +1835,5 @@
 
 /**
- * Called to perform the job of the bios.
- *
- * @returns VBox status.
- * @param   pDevIns     Device instance of the first bus.
+ * @interface_method_impl{PDMPCIBUSREG,pfnFakePCIBIOSR3}
  */
 static DECLCALLBACK(int) pciR3FakePCIBIOS(PPDMDEVINS pDevIns)
@@ -1942,26 +1890,22 @@
 }
 
-/**
- * Info handler, device version.
- *
- * @param   pDevIns     Device instance which registered the info.
- * @param   pHlp        Callback functions for doing output.
- * @param   pszArgs     Argument string. Optional and specific to the handler.
+
+/* -=-=-=-=-=- Debug Info Handlers -=-=-=-=-=- */
+
+/**
+ * @callback_method_impl{FNDBGFHANDLERDEV}
  */
 static DECLCALLBACK(void) pciR3IrqInfo(PPDMDEVINS pDevIns, PCDBGFINFOHLP pHlp, const char *pszArgs)
 {
     PPCIGLOBALS pGlobals = PDMINS_2_DATA(pDevIns, PPCIGLOBALS);
-    uint16_t    router;
-    uint8_t     irq_map;
-    int         i;
     NOREF(pszArgs);
 
-    router = pGlobals->PIIX3State.dev.devfn;
+    uint16_t router = pGlobals->PIIX3State.dev.devfn;
     pHlp->pfnPrintf(pHlp, "PCI interrupt router at: %02X:%02X:%X\n",
                     router >> 8, (router >> 3) & 0x1f, router & 0x7);
 
-    for (i = 0; i < 4; ++i)
-    {
-        irq_map = pci_config_readb(pGlobals, 0, router, 0x60 + i);
+    for (int i = 0; i < 4; ++i)
+    {
+        uint8_t irq_map = pci_config_readb(pGlobals, 0, router, 0x60 + i);
         if (irq_map & 0x80)
             pHlp->pfnPrintf(pHlp, "PIRQ%c disabled\n", 'A' + i);
@@ -1971,4 +1915,10 @@
 }
 
+/**
+ * Outputs indent.
+ *
+ * @param   pHlp        Output helpers.
+ * @param   iIndent     Indentation level.
+ */
 static void pciR3PrintIndent(PCDBGFINFOHLP pHlp, int iIndent)
 {
@@ -1977,4 +1927,13 @@
 }
 
+/**
+ * Recursive worker for pciR3Info.
+ *
+ * @param   pBus        The bus to display.
+ * @param   pHlp        Output helpers.
+ * @param   iIndent     Indentation level.
+ * @param   fRegisters  Whether to also display the PCI configuration registers
+ *                      of each device on the bus.
+ */
 static void pciR3BusInfo(PPCIBUS pBus, PCDBGFINFOHLP pHlp, int iIndent, bool fRegisters)
 {
@@ -2081,10 +2040,7 @@
 }
 
-/**
- * Info handler, device version.
- *
- * @param   pDevIns     Device instance which registered the info.
- * @param   pHlp        Callback functions for doing output.
- * @param   pszArgs     Argument string. Optional and specific to the handler.
+
+/**
+ * @callback_method_impl{FNDBGFHANDLERDEV}
  */
 static DECLCALLBACK(void) pciR3Info(PPDMDEVINS pDevIns, PCDBGFINFOHLP pHlp, const char *pszArgs)
@@ -2100,6 +2056,9 @@
 }
 
-/**
- * @copydoc FNPDMDEVRELOCATE
+
+/* -=-=-=-=-=- PDMDEVREG  -=-=-=-=-=- */
+
+/**
+ * @interface_method_impl{PDMDEVREG,pfnRelocate}
  */
 static DECLCALLBACK(void) pciR3Relocate(PPDMDEVINS pDevIns, RTGCINTPTR offDelta)
@@ -2122,5 +2081,5 @@
 
 /**
- * @copydoc FNPDMDEVRESET
+ * @interface_method_impl{PDMDEVREG,pfnReset}
  */
 static DECLCALLBACK(void) pciR3Reset(PPDMDEVINS pDevIns)
@@ -2128,4 +2087,5 @@
     pciR3FakePCIBIOS(pDevIns);
 }
+
 
 /**
@@ -2343,12 +2303,9 @@
 
 
-/**
- * Set the IRQ for a PCI device on a secondary bus.
- *
- * @param   pDevIns         Device instance of the PCI Bus.
- * @param   pPciDev         The PCI device structure.
- * @param   iIrq            IRQ number to set.
- * @param   iLevel          IRQ level.
- * @param   uTagSrc         The IRQ tag and source ID (for tracing).
+
+/* -=-=-=-=-=- The PCI bridge specific bits -=-=-=-=-=- */
+
+/**
+ * @interface_method_impl{PDMPCIBUSREG,pfnSetIrq}
  */
 PDMBOTHCBDECL(void) pcibridgeSetIrq(PPDMDEVINS pDevIns, PPCIDEVICE pPciDev, int iIrq, int iLevel, uint32_t uTagSrc)
@@ -2390,5 +2347,5 @@
     PPCIBUS pBus = PDMINS_2_DATA(pDevIns, PPCIBUS);
 
-    LogFlowFunc((": pDevIns=%p iBus=%d iDevice=%d u32Address=%u u32Value=%u cb=%d\n", pDevIns, iBus, iDevice, u32Address, u32Value, cb));
+    LogFlowFunc(("pDevIns=%p iBus=%d iDevice=%d u32Address=%u u32Value=%u cb=%d\n", pDevIns, iBus, iDevice, u32Address, u32Value, cb));
 
     /* If the current bus is not the target bus search for the bus which contains the device. */
@@ -2414,4 +2371,5 @@
 }
 
+
 /**
  * @callback_method_impl{FNPCIBRIDGECONFIGREAD}
@@ -2422,5 +2380,5 @@
     uint32_t u32Value = 0xffffffff; /* Return value in case there is no device. */
 
-    LogFlowFunc((": pDevIns=%p iBus=%d iDevice=%d u32Address=%u cb=%d\n", pDevIns, iBus, iDevice, u32Address, cb));
+    LogFlowFunc(("pDevIns=%p iBus=%d iDevice=%d u32Address=%u cb=%d\n", pDevIns, iBus, iDevice, u32Address, cb));
 
     /* If the current bus is not the target bus search for the bus which contains the device. */
@@ -2450,5 +2408,5 @@
 
 /**
- * @copydoc FNSSMDEVSAVEEXEC
+ * @callback_method_impl{FNSSMDEVSAVEEXEC}
  */
 static DECLCALLBACK(int) pcibridgeR3SaveExec(PPDMDEVINS pDevIns, PSSMHANDLE pSSM)
@@ -2460,5 +2418,5 @@
 
 /**
- * @copydoc FNSSMDEVLOADEXEC
+ * @callback_method_impl{FNSSMDEVLOADEXEC}
  */
 static DECLCALLBACK(int) pcibridgeR3LoadExec(PPDMDEVINS pDevIns, PSSMHANDLE pSSM, uint32_t uVersion, uint32_t uPass)
@@ -2472,13 +2430,5 @@
 
 /**
- * Registers the device with the default PCI bus.
- *
- * @returns VBox status code.
- * @param   pDevIns         Device instance of the PCI Bus.
- * @param   pPciDev         The PCI device structure.
- *                          Any PCI enabled device must keep this in it's instance data!
- *                          Fill in the PCI data config before registration, please.
- * @param   pszName         Pointer to device name (permanent, readonly). For debugging, not unique.
- * @param   iDev            The PCI device number. Use a negative value for auto assigning one.
+ * @interface_method_impl{PDMPCIBUSREG,pfnRegister}
  */
 static DECLCALLBACK(int) pcibridgeR3RegisterDevice(PPDMDEVINS pDevIns, PPCIDEVICE pPciDev, const char *pszName, int iDev)
@@ -2505,5 +2455,5 @@
 
 /**
- * @copydoc FNPDMDEVRESET
+ * @interface_method_impl{PDMDEVREG, pfnReset}
  */
 static DECLCALLBACK(void) pcibridgeR3Reset(PPDMDEVINS pDevIns)
@@ -2519,5 +2469,5 @@
 
 /**
- * @copydoc FNPDMDEVRELOCATE
+ * @interface_method_impl{PDMDEVREG, pfnRelocate}
  */
 static DECLCALLBACK(void) pcibridgeR3Relocate(PPDMDEVINS pDevIns, RTGCINTPTR offDelta)
@@ -2612,5 +2562,5 @@
      * devices attached to the bus is unaffected.
      */
-    PCIDevSetInterruptPin (&pBus->PciDev, 0x00);
+    PCIDevSetInterruptPin(&pBus->PciDev, 0x00);
 
     pBus->PciDev.pDevIns                    = pDevIns;
@@ -2624,5 +2574,5 @@
      * Register this PCI bridge. The called function will take care on which bus we will get registered.
      */
-    rc = PDMDevHlpPCIRegister (pDevIns, &pBus->PciDev);
+    rc = PDMDevHlpPCIRegister(pDevIns, &pBus->PciDev);
     if (RT_FAILURE(rc))
         return rc;
