Changeset 82213 in vbox for trunk/src

Timestamp:

Nov 26, 2019 2:08:48 AM (5 years ago)

Author:

vboxsync

Message:

doxygen fixes. bugref:9218

Location:

trunk/src/VBox

Files:

• Devices/Input/DevPS2.cpp (modified) (4 diffs)
• Devices/Input/DevPS2K.cpp (modified) (8 diffs)
• Devices/Input/DevPS2M.cpp (modified) (6 diffs)
• Devices/Input/DrvKeyboardQueue.cpp (modified) (8 diffs)
• Devices/Input/UsbKbd.cpp (modified) (4 diffs)
• Main/src-client/KeyboardImpl.cpp (modified) (1 diff)

trunk/src/VBox/Devices/Input/DevPS2.cpp

@@ -735 +735 @@
  * @param   pQHdr       The queue header.
  * @param   cElements   The queue size.
- * @param   abElements  The queue element array.
+ * @param   pbElements  The queue element array.
  * @param   bValue      The byte to store.
  */
@@ -771 +771 @@
  * @param   pQHdr       The queue header.
  * @param   cElements   The queue size.
- * @param   abElements  The queue element array.
+ * @param   pbElements  The queue element array.
  * @param   pbValue     Where to return the byte on success.
  *
@@ -817 +817 @@
  * @param   pQHdr       The queue header.
  * @param   cElements   The queue size.
- * @param   abElements  The queue element array.
+ * @param   pbElements  The queue element array.
  */
 void PS2CmnR3SaveQueue(PCPDMDEVHLPR3 pHlp, PSSMHANDLE pSSM, PPS2QHDR pQHdr, size_t cElements, uint8_t const *pbElements)
@@ -842 +842 @@
  * @param   pQHdr       The queue header.
  * @param   cElements   The queue size.
- * @param   abElements  The queue element array.
+ * @param   pbElements  The queue element array.
  *
  * @returns VBox status/error code.

trunk/src/VBox/Devices/Input/DevPS2K.cpp

@@ -914 +914 @@
 
 /**
- * @callback_function_impl{FNTMTIMERDEV}
+ * @callback_method_impl{FNTMTIMERDEV}
  *
  * Throttling timer to emulate the finite keyboard communication speed. A PS/2 keyboard is
@@ -950 +950 @@
 
 /**
- * @callback_function_impl{FNTMTIMERDEV,
+ * @callback_method_impl{FNTMTIMERDEV,
  * Timer handler for emulating typematic keys.}
  *
@@ -978 +978 @@
 
 /**
- * @callback_function_impl{FNTMTIMERDEV}
+ * @callback_method_impl{FNTMTIMERDEV}
  *
  * The keyboard BAT is specified to take several hundred milliseconds. We need
@@ -1056 +1056 @@
  * @param   pDevIns     The device instance.
  * @param   pThis       The PS2 keyboard instance data.
- * @param   u32Usage    USB HID usage code with key press/release flag.
- */
-static int ps2kR3PutEventWorker(PPDMDEVINS pDevIns, PPS2K pThis, uint32_t u32Usage)
+ * @param   idUsage     USB HID usage code with key press/release flag.
+ */
+static int ps2kR3PutEventWorker(PPDMDEVINS pDevIns, PPS2K pThis, uint32_t idUsage)
 {
     uint32_t        u32HidCode;
@@ -1068 +1068 @@
 
     /* Extract the usage page and ID and ensure it's valid. */
-    fKeyDown   = !(u32Usage & 0x80000000);
-    u32HidCode = u32Usage & 0xFFFFFF;
-    u8HidPage  = RT_LOBYTE(RT_HIWORD(u32Usage));
-    u8KeyCode  = RT_LOBYTE(u32Usage);
+    fKeyDown   = !(idUsage & UINT32_C(0x80000000));
+    u32HidCode = idUsage & 0xFFFFFF;
+    u8HidPage  = RT_LOBYTE(RT_HIWORD(idUsage));
+    u8KeyCode  = RT_LOBYTE(idUsage);
     if (u8HidPage == USB_HID_KB_PAGE)
         AssertReturn(u8KeyCode <= VBOX_USB_MAX_USAGE_CODE, VERR_INTERNAL_ERROR);
@@ -1107 +1107 @@
  * @interface_method_impl{PDMIKEYBOARDPORT,pfnPutEventHid}
  */
-static DECLCALLBACK(int) ps2kR3KeyboardPort_PutEventHid(PPDMIKEYBOARDPORT pInterface, uint32_t u32UsageCode)
+static DECLCALLBACK(int) ps2kR3KeyboardPort_PutEventHid(PPDMIKEYBOARDPORT pInterface, uint32_t idUsage)
 {
     PPS2KR3     pThisCC = RT_FROM_MEMBER(pInterface, PS2KR3, Keyboard.IPort);
@@ -1114 +1114 @@
     int         rc;
 
-    LogRelFlowFunc(("key code %08X\n", u32UsageCode));
+    LogRelFlowFunc(("key code %08X\n", idUsage));
 
     rc = PDMDevHlpCritSectEnter(pDevIns, pDevIns->pCritSectRoR3, VERR_SEM_BUSY);
@@ -1122 +1122 @@
      * key is allowed to use this scancode.
      */
-    if (RT_LIKELY(u32UsageCode != KRSP_BAT_FAIL))
-        ps2kR3PutEventWorker(pDevIns, pThis, u32UsageCode);
+    if (RT_LIKELY(idUsage != KRSP_BAT_FAIL))
+        ps2kR3PutEventWorker(pDevIns, pThis, idUsage);
     else
         ps2kR3ReleaseKeys(pDevIns, pThis);

trunk/src/VBox/Devices/Input/DevPS2M.cpp

@@ -416 +416 @@
  *
  * @param   pDevIns The device instance.
- * @param   pThis   The PS/2 auxiliary device instance data.
+ * @param   pThis   The PS/2 auxiliary device shared instance data.
  * @param   cmd     The command (or data) byte.
  */
@@ -638 +638 @@
  *
  * @returns VINF_SUCCESS or VINF_TRY_AGAIN.
- * @param   pThis               The PS/2 auxiliary device instance data.
- * @param   pb                  Where to return the byte we've read.
+ * @param   pThis   The PS/2 auxiliary device shared instance data.
+ * @param   pb      Where to return the byte we've read.
  * @remarks Caller must have entered the device critical section.
  */
@@ -673 +673 @@
 
 /**
- * @callback_function_impl{FNTMTIMERDEV,
+ * @callback_method_impl{FNTMTIMERDEV,
  * Event rate throttling timer to emulate the auxiliary device sampling rate.}
  */
@@ -704 +704 @@
 
 /**
- * @callback_function_impl{FNTMTIMERDEV}
+ * @callback_method_impl{FNTMTIMERDEV}
  *
  * The auxiliary device reset is specified to take up to about 500 milliseconds.
@@ -768 +768 @@
  * @returns VBox status code.
  * @param   pDevIns     The device instance.
- * @param   pThis       The PS/2 auxiliary device instance data.
+ * @param   pThis       The PS/2 auxiliary device shared instance data.
  * @param   dx          X direction movement delta.
  * @param   dy          Y direction movement delta.
@@ -883 +883 @@
  *
  * @returns VBox status code.
- * @param   pThis       The PS/2 auxiliary device instance data.
  * @param   pDevIns     The device instance.
+ * @param   pThisCC     The PS/2 auxiliary device instance data for ring-3.
  * @param   iLUN        The logical unit which is being detached.
  * @param   fFlags      Flags, combination of the PDMDEVATT_FLAGS_* \#defines.

trunk/src/VBox/Devices/Input/DrvKeyboardQueue.cpp

@@ -83 +83 @@
     PDMQUEUEITEMCORE    Core;
     /** The keycode. */
-    uint32_t            u32UsageCode;
+    uint32_t            idUsage;
 } DRVKBDQUEUEITEM, *PDRVKBDQUEUEITEM;
 
@@ -212 +212 @@
 
 /**
- * Queues a scancode-based keyboard event.
+ * @interface_method_impl{PDMIKEYBOARDPORT,pfnPutEventScan}
+ *
  * Because of the event queueing the EMT context requirement is lifted.
- *
- * @returns VBox status code.
- * @param   pInterface          Pointer to this interface structure.
- * @param   u8ScanCode          The scan code to translate/queue.
  * @thread  Any thread.
  */
@@ -227 +224 @@
         return VINF_SUCCESS;
 
-    uint32_t    u32Usage = 0;
-    pDrv->XlatState = ScancodeToHidUsage(pDrv->XlatState, u8ScanCode, &u32Usage);
-
-    if (pDrv->XlatState == SS_IDLE) {
+    uint32_t idUsage = 0;
+    pDrv->XlatState = ScancodeToHidUsage(pDrv->XlatState, u8ScanCode, &idUsage);
+
+    if (pDrv->XlatState == SS_IDLE)
+    {
         PDRVKBDQUEUEITEM pItem = (PDRVKBDQUEUEITEM)PDMQueueAlloc(pDrv->pQueue);
         if (pItem)
@@ -239 +237 @@
              * key up into a key up/key down sequence.
              */
-            if (u32Usage == 0x80000090 || u32Usage == 0x80000091)
+            if (idUsage == UINT32_C(0x80000090) || idUsage == UINT32_C(0x80000091))
             {
                 PDRVKBDQUEUEITEM pItem2 = (PDRVKBDQUEUEITEM)PDMQueueAlloc(pDrv->pQueue);
@@ -249 +247 @@
                 {
                     /* Manufacture a key down event. */
-                    pItem2->u32UsageCode = u32Usage & ~0x80000000;
+                    pItem2->idUsage = idUsage & ~UINT32_C(0x80000000);
                     PDMQueueInsert(pDrv->pQueue, &pItem2->Core);
                 }
             }
 
-            pItem->u32UsageCode = u32Usage;
+            pItem->idUsage = idUsage;
             PDMQueueInsert(pDrv->pQueue, &pItem->Core);
 
@@ -269 +267 @@
 
 /**
- * Queues a HID-usage-based keyboard event.
+ * @interface_method_impl{PDMIKEYBOARDPORT,pfnPutEventHid}
+ *
  * Because of the event queueing the EMT context requirement is lifted.
- *
- * @returns VBox status code.
- * @param   pInterface          Pointer to this interface structure.
- * @param   u32UsageCode        The HID usage code to queue.
  * @thread  Any thread.
  */
-static DECLCALLBACK(int) drvKbdQueuePutEventHid(PPDMIKEYBOARDPORT pInterface, uint32_t u32UsageCode)
+static DECLCALLBACK(int) drvKbdQueuePutEventHid(PPDMIKEYBOARDPORT pInterface, uint32_t idUsage)
 {
     PDRVKBDQUEUE pDrv = IKEYBOARDPORT_2_DRVKBDQUEUE(pInterface);
@@ -287 +282 @@
     if (pItem)
     {
-        pItem->u32UsageCode = u32UsageCode;
+        pItem->idUsage = idUsage;
         PDMQueueInsert(pDrv->pQueue, &pItem->Core);
 
@@ -357 +352 @@
     PDRVKBDQUEUE        pThis = PDMINS_2_DATA(pDrvIns, PDRVKBDQUEUE);
     PDRVKBDQUEUEITEM    pItem = (PDRVKBDQUEUEITEM)pItemCore;
-    int rc = pThis->pUpPort->pfnPutEventHid(pThis->pUpPort, pItem->u32UsageCode);
+    int rc = pThis->pUpPort->pfnPutEventHid(pThis->pUpPort, pItem->idUsage);
     return RT_SUCCESS(rc);
 }

trunk/src/VBox/Devices/Input/UsbKbd.cpp

@@ -700 +700 @@
 
 /**
- * Keyboard event handler.
- *
- * @returns VBox status code.
- * @param   pInterface      Pointer to the keyboard port interface (KBDState::Keyboard.IPort).
- * @param   u32UsageCode    The key usage ID.
- */
-static DECLCALLBACK(int) usbHidKeyboardPutEvent(PPDMIKEYBOARDPORT pInterface, uint32_t u32UsageCode)
+ * @interface_method_impl{PDMIKEYBOARDPORT,pfnPutEventHid}
+ */
+static DECLCALLBACK(int) usbHidKeyboardPutEvent(PPDMIKEYBOARDPORT pInterface, uint32_t idUsage)
 {
     PUSBHID pThis = RT_FROM_MEMBER(pInterface, USBHID, Lun0.IPort);
@@ -714 +710 @@
     int         rc = VINF_SUCCESS;
 
+    /* Let's see what we got... */
+    fKeyDown  = !(idUsage & UINT32_C(0x80000000));
+    u8HidCode = idUsage & 0xFF;
+    AssertReturn(u8HidCode <= VBOX_USB_MAX_USAGE_CODE, VERR_INTERNAL_ERROR);
+
     RTCritSectEnter(&pThis->CritSect);
-
-    /* Let's see what we got... */
-    fKeyDown  = !(u32UsageCode & 0x80000000);
-    u8HidCode = u32UsageCode & 0xFF;
-    AssertReturn(u8HidCode <= VBOX_USB_MAX_USAGE_CODE, VERR_INTERNAL_ERROR);
 
     LogFlowFunc(("key %s: 0x%x\n", fKeyDown ? "down" : "up", u8HidCode));
@@ -737 +733 @@
     else if (fHaveEvent)
     {
-        if (RT_UNLIKELY(u32UsageCode == KRSP_BAT_FAIL))
-        {
-            /* Clear all currently depressed and unreported keys. */
-            RT_ZERO(pThis->abDepressedKeys);
-        }
-        else
+        if (RT_LIKELY(idUsage != KRSP_BAT_FAIL))
         {
             /* Regular key event - update keyboard state. */
@@ -749 +740 @@
             else
                 pThis->abDepressedKeys[u8HidCode] = 0;
+        }
+        else
+        {
+            /* Clear all currently depressed and unreported keys. */
+            RT_ZERO(pThis->abDepressedKeys);
         }
 

trunk/src/VBox/Main/src-client/KeyboardImpl.cpp

@@ -255 +255 @@
         return S_OK;
 
-    int vrc = VINF_SUCCESS;
-    uint32_t u32Usage;
-    u32Usage = (uint16_t)aUsageCode | ((uint32_t)(uint8_t)aUsagePage << 16) | (fKeyRelease ? 0x80000000 : 0);
-    vrc = pUpPort->pfnPutEventHid(pUpPort, u32Usage);
+    uint32_t idUsage = (uint16_t)aUsageCode | ((uint32_t)(uint8_t)aUsagePage << 16) | (fKeyRelease ? UINT32_C(0x80000000) : 0);
+    int vrc = pUpPort->pfnPutEventHid(pUpPort, idUsage);
     if (RT_FAILURE(vrc))
         return setErrorBoth(VBOX_E_IPRT_ERROR, vrc,