Changeset 58052 in vbox for trunk/src/VBox/Additions

Timestamp:

Oct 6, 2015 1:45:20 PM (10 years ago)

Author:

vboxsync

svn:sync-xref-src-repo-rev:

103106

Message:

VBoxService: More service introduction pages. A few more cleanups.

Location:

trunk/src/VBox/Additions/common/VBoxService

Files:

• VBoxServiceAutoMount.cpp (modified) (2 diffs)
• VBoxServiceBalloon.cpp (modified) (1 diff)
• VBoxServiceClipboard-os2.cpp (modified) (8 diffs)
• VBoxServiceControl.cpp (modified) (1 diff)
• VBoxServiceCpuHotPlug.cpp (modified) (8 diffs)
• VBoxServicePageSharing.cpp (modified) (1 diff)
• VBoxServiceTimeSync.cpp (modified) (1 diff)
• VBoxServiceVMInfo.cpp (modified) (1 diff)

trunk/src/VBox/Additions/common/VBoxService/VBoxServiceAutoMount.cpp

@@ -14 +14 @@
  * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
  * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
+ */
+
+
+/** @page pg_vgsvc_automount VBoxService - Shared Folder Automounter
+ *
+ * The Shared Folder Automounter subservice mounts shared folders upon request
+ * from the host.
+ *
+ * This retrieves shared folder automount requests from Main via the VMMDev.
+ * The current implemention only does this once, for some inexplicable reason,
+ * so the run-time addition of automounted shared folders are not heeded.
+ *
+ * This subservice is only used on linux and solaris.  On Windows the current
+ * thinking is this is better of done from VBoxTray, some one argue that for
+ * drive letter assigned shared folders it would be better to do some magic here
+ * (obviously not involving NDAddConnection).
+ *
  */
 
@@ -602 +619 @@
      * for the pfShutdown flag to be set by the main thread.
      */
+/** @todo r=bird: Shared folders have always been configurable at run time, so
+ * this service must be changed to check for changes and execute those changes!
+ *
+ * The 0.5sec sleep here is just soo crude and must go!
+ */
     for (;;)
     {

trunk/src/VBox/Additions/common/VBoxService/VBoxServiceBalloon.cpp

@@ -14 +14 @@
  * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
  * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
+ */
+
+
+/** @page pg_vgsvc_memballoon VBoxService - Memory Ballooning
+ *
+ * The Memory Ballooning subservice works with VBoxGuest, PGM and GMM to
+ * dynamically reallocate memory between VMs.
+ *
+ * Memory ballooning is typically used to deal with overcomitting memory on the
+ * host.  It allowes you to borrow memory from one or more VMs and make it
+ * available to others.  In theory it could also be used to make memory
+ * available to the host system, however memory fragmentation typically makes
+ * that difficult.
+ *
+ * The memory ballooning subservices talks to PGM, GMM and Main via the VMMDev.
+ * It polls for change requests at an interval and executes them when they
+ * arrive.  There are two ways we implement the actual ballooning, either
+ * VBoxGuest allocates kernel memory and donates it to the host, or this service
+ * allocates process memory which VBoxGuest then locks down and donates to the
+ * host.  While we prefer the former method it is not practicable on all OS and
+ * we have to use the latter.
+ *
  */
 

trunk/src/VBox/Additions/common/VBoxService/VBoxServiceClipboard-os2.cpp

@@ -14 +14 @@
  * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
  * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
+ */
+
+
+/** @page pg_vgsvc_clipboard VBoxService - Clipboard (OS/2)
+ *
+ * The Clipboard subservice provides clipboard sharing for OS/2 guests only.
+ *
+ * This was the second subservice that was added to VBoxService.  OS/2 is a
+ * single user system and we don't provide any VBoxTray or VBoxClient like
+ * processes. Because it's kind of simple system, it became natural to put the
+ * clipboard sharing here in VBoxService for OS/2.
+ *
+ * In addition to integrating with the native OS/2 PM clipboard formats, we also
+ * try provide the Odin32, a windows API layer for OS/2 (developed by Sander van
+ * Leeuwen and friends, later mainly InnoTek), with additional formats.
+ *
+ * Bitmaps are currently not supported, but that can easily be added should the
+ * need ever arrise.
  */
 
@@ -203 +221 @@
                 if (g_atomOdin32UnicodeText == 0)
                     VGSvcError("WinAddAtom() failed, lasterr=%lx; WinFindAtom() failed, lasterror=%lx\n",
-                                     lLastError, WinGetLastError(g_habCtrl));
+                               lLastError, WinGetLastError(g_habCtrl));
 
                 VGSvcVerbose(2, "g_u32ClientId=%RX32 g_atomNothingChanged=%#x g_atomOdin32UnicodeText=%#x\n",
-                                   g_u32ClientId, g_atomNothingChanged, g_atomOdin32UnicodeText);
+                             g_u32ClientId, g_atomNothingChanged, g_atomOdin32UnicodeText);
                 return VINF_SUCCESS;
             }
@@ -214 +232 @@
         else
             VGSvcError("WinAddAtom() failed, lasterr=%lx; WinFindAtom() failed, lasterror=%lx\n",
-                             lLastError, WinGetLastError(g_habCtrl));
+                       lLastError, WinGetLastError(g_habCtrl));
     }
     else
@@ -291 +309 @@
                     if (!WinSetClipbrdData(g_habWorker, 0, CF_TEXT, CFI_POINTER))
                         VGSvcError("WinSetClipbrdData(,,CF_TEXT,) failed, lasterr=%lx\n", WinGetLastError(g_habWorker));
-                    if (    g_atomOdin32UnicodeText
-                        &&  !WinSetClipbrdData(g_habWorker, 0, g_atomOdin32UnicodeText, CFI_POINTER))
+                    if (   g_atomOdin32UnicodeText
+                        && !WinSetClipbrdData(g_habWorker, 0, g_atomOdin32UnicodeText, CFI_POINTER))
                         VGSvcError("WinSetClipbrdData(,,g_atomOdin32UnicodeText,) failed, lasterr=%lx\n", WinGetLastError(g_habWorker));
                 }
@@ -486 +504 @@
                 {
                     VGSvcError("vgsvcClipboardOs2RenderFormat: WinSetClipbrdData(,%p,%#x, CF_POINTER) failed, lasterror=%lx\n",
-                                     pvPM, usFmt, WinGetLastError(g_habWorker));
+                               pvPM, usFmt, WinGetLastError(g_habWorker));
                     DosFreeMem(pvPM);
                 }
@@ -879 +897 @@
                                             MPFROMLONG(fFormats), 0))
                                 VGSvcError("WinPostMsg(%lx, FORMATS,,) failed, lasterr=%#lx\n",
-                                                 g_hwndWorker, WinGetLastError(g_habListener));
+                                           g_hwndWorker, WinGetLastError(g_habListener));
                             break;
 
@@ -889 +907 @@
                                             MPFROMLONG(fFormats), 0))
                                 VGSvcError("WinPostMsg(%lx, READ_DATA,,) failed, lasterr=%#lx\n",
-                                                 g_hwndWorker, WinGetLastError(g_habListener));
+                                           g_hwndWorker, WinGetLastError(g_habListener));
                             break;
 
@@ -994 +1012 @@
                                 if (qmsg.msg != WM_TIMER)
                                     VGSvcVerbose(6, "WinGetMsg -> hwnd=%p msg=%#x mp1=%p mp2=%p time=%#x ptl=%d,%d rsrv=%#x\n",
-                                                       qmsg.hwnd, qmsg.msg, qmsg.mp1, qmsg.mp2, qmsg.time, qmsg.ptl.x, qmsg.ptl.y, qmsg.reserved);
+                                                 qmsg.hwnd, qmsg.msg, qmsg.mp1, qmsg.mp2, qmsg.time, qmsg.ptl.x, qmsg.ptl.y, qmsg.reserved);
                                 WinDispatchMsg(g_habWorker, &qmsg);
                             }

trunk/src/VBox/Additions/common/VBoxService/VBoxServiceControl.cpp

@@ -19 +19 @@
  *
  * The Guest Control subservice helps implementing the IGuest APIs.
+ *
+ * The communication between this service (and its children) and IGuest goes
+ * over the HGCM GuestControl service.
  *
  * The IGuest APIs provides means to manipulate (control) files, directories,

trunk/src/VBox/Additions/common/VBoxService/VBoxServiceCpuHotPlug.cpp

@@ -1 +1 @@
 /* $Id$ */
 /** @file
- * VBoxService - Guest Additions CPU Hot Plugging Service.
+ * VBoxService - Guest Additions CPU Hot-Plugging Service.
  */
 
@@ -16 +16 @@
  */
 
+/** @page pg_vgsvc_cpuhotplug CPU Hot-Plugging
+ *
+ * The CPU Hot-Plugging subservice helps execute and coordinate CPU hot-plugging
+ * between the guest OS and the VMM.
+ *
+ * CPU Hot-Plugging is useful for reallocating CPU resources from one VM to
+ * other VMs or/and the host.  It talks to the VMM via VMMDev, new hot-plugging
+ * events being signalled with an interrupt (no polling).
+ *
+ * Currently only supported for linux guests.
+ */
 
 /*********************************************************************************************************************************
@@ -96 +107 @@
 {
     /** device:<id> */
-    {true, "device:*"},
+    { true, "device:*" },
     /** LNXSYBUS:<id> */
-    {true, "LNXSYBUS:*"}
+    { true, "LNXSYBUS:*" }
 };
 
@@ -105 +116 @@
 {
     /** ACPI0004:<id> */
-    {true, "ACPI0004:*"}
+    { true, "ACPI0004:*" }
 };
 
@@ -112 +123 @@
 {
     /** LNXCPU:<id> */
-    {true, "LNXCPU:*"},
+    { true, "LNXCPU:*" },
     /** ACPI_CPU:<id> */
-    {true, "ACPI_CPU:*"}
+    { true, "ACPI_CPU:*" }
 };
 
@@ -121 +132 @@
 {
     /** Level 1 */
-    {ACPI_CPU_PATH_NOT_PROBED, g_aAcpiCpuPathLvl1, RT_ELEMENTS(g_aAcpiCpuPathLvl1), NULL, NULL},
+    { ACPI_CPU_PATH_NOT_PROBED, g_aAcpiCpuPathLvl1, RT_ELEMENTS(g_aAcpiCpuPathLvl1), NULL, NULL },
     /** Level 2 */
-    {ACPI_CPU_PATH_NOT_PROBED, g_aAcpiCpuPathLvl2, RT_ELEMENTS(g_aAcpiCpuPathLvl2), NULL, NULL},
+    { ACPI_CPU_PATH_NOT_PROBED, g_aAcpiCpuPathLvl2, RT_ELEMENTS(g_aAcpiCpuPathLvl2), NULL, NULL },
     /** Level 3 */
-    {ACPI_CPU_PATH_NOT_PROBED, g_aAcpiCpuPathLvl3, RT_ELEMENTS(g_aAcpiCpuPathLvl3), NULL, NULL},
+    { ACPI_CPU_PATH_NOT_PROBED, g_aAcpiCpuPathLvl3, RT_ELEMENTS(g_aAcpiCpuPathLvl3), NULL, NULL },
     /** Level 4 */
-    {ACPI_CPU_PATH_NOT_PROBED, g_aAcpiCpuPathLvl4, RT_ELEMENTS(g_aAcpiCpuPathLvl4), NULL, NULL},
+    { ACPI_CPU_PATH_NOT_PROBED, g_aAcpiCpuPathLvl4, RT_ELEMENTS(g_aAcpiCpuPathLvl4), NULL, NULL },
 };
 
@@ -553 +564 @@
     for (;;)
     {
-        /* Wait for CPU hot plugging event. */
+        /* Wait for CPU hot-plugging event. */
         uint32_t            idCpuCore;
         uint32_t            idCpuPackage;
@@ -613 +624 @@
     "cpuhotplug",
     /* pszDescription. */
-    "CPU hot plugging monitor",
+    "CPU hot-plugging monitor",
     /* pszUsage. */
     NULL,

trunk/src/VBox/Additions/common/VBoxService/VBoxServicePageSharing.cpp

@@ -16 +16 @@
  */
 
+
 /** @page pg_vgsvc_pagesharing VBoxService - Page Sharing
  *
- * The Page Sharing subservice is the driving force in implementing the Page
- * Fusion feature in VirtualBox.   It is its responsibility to find memory
- * mappings and other good candidates for page sharing.
+ * The Page Sharing subservice is responsible for finding memory mappings
+ * suitable page fusions.
+ *
+ * It is the driving force behind the Page Fusion feature in VirtualBox.
+ * Working with PGM and GMM (ring-0) thru the VMMDev interface.  Every so often
+ * it reenumerates the memory mappings (executables and shared libraries) of the
+ * guest OS and reports additions and removals to GMM.  For each mapping there
+ * is a filename and version as well as and address range and subsections.  GMM
+ * will match the mapping with mapping with the same name and version from other
+ * VMs and see if there are any identical pages between the two.
+ *
+ * To increase the hit rate and reduce the volatility, the service launches a
+ * child process which loads all the Windows system DLLs it can.  The child
+ * process is necessary as the DLLs are loaded without running the init code,
+ * and therefore not actually callable for other VBoxService code (may crash).
  *
  * This is currently only implemented on Windows.  There is no technical reason
  * for it not to be doable for all the other guests too, it's just a matter of
  * customer demand and engineering time.
+ *
  */
 

trunk/src/VBox/Additions/common/VBoxService/VBoxServiceTimeSync.cpp

@@ -19 +19 @@
 /** @page pg_vgsvc_timesync     VBoxService - The Time Sync Service
  *
+ * The time sync subservice synchronizes the guest OS walltime with the host.
+ *
  * The time sync service plays along with the Time Manager (TM) in the VMM
  * to keep the guest time accurate using the host machine as reference.
- * TM will try its best to make sure all timer ticks gets delivered so that
- * there isn't normally any need to adjust the guest time.
+ * Communication is facilitated by VMMDev.  TM will try its best to make sure
+ * all timer ticks gets delivered so that there isn't normally any need to
+ * adjust the guest time.
  *
  * There are three normal (= acceptable) cases:

trunk/src/VBox/Additions/common/VBoxService/VBoxServiceVMInfo.cpp

@@ -19 +19 @@
  *
  * The VM Information subservice provides heaps of useful information about the
- * VM via guest properties.  Check out the "/VirtualBox/GuestInfo/" part of the
- * guest properties.
+ * VM via guest properties.
+ *
+ * Guest properties is a limited database maintained by the HGCM GuestProperties
+ * service in cooperation with the Main API (VBoxSVC).  Properties have a name
+ * (ours are path like), a string value, and a nanosecond timestamp (unix
+ * epoch).  The timestamp lets the user see how recent the information is.  As
+ * an laternative to polling on changes, it is also possible to wait on changes
+ * via the Main API or VBoxManage on the host side and VBoxControl in the guest.
+ *
+ * The namespace "/VirtualBox/" is reserved for value provided by VirtualBox.
+ * This service provides all the information under "/VirtualBox/GuestInfo/".
  *
  *