Changeset 58033 in vbox for trunk

Timestamp:

Oct 5, 2015 10:12:28 PM (9 years ago)

Author:

vboxsync

Message:

VBoxService: Started adding pages with some details for each component.

Location:

trunk/src/VBox/Additions/common/VBoxService

Files:

• VBoxService.cpp (modified) (1 diff)
• VBoxServiceControl.cpp (modified) (1 diff)
• VBoxServicePageSharing.cpp (modified) (1 diff)
• VBoxServiceStats.cpp (modified) (1 diff)
• VBoxServiceTimeSync.cpp (modified) (2 diffs)
• VBoxServiceVMInfo.cpp (modified) (2 diffs)

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

@@ -17 +17 @@
 
 
+/** @page pg_vgsvc VBoxService
+ *
+ * VBoxService is a root daemon for implementing guest additions features.
+ *
+ * It is structured as one binary that contains many sub-services.  The reason
+ * for this is partially historical and partially practical.  The practical
+ * reason is that the VBoxService binary is typically statically linked, at
+ * least with IPRT and the guest library, so we save quite a lot of space having
+ * on single binary instead individual binaries for each sub-service and their
+ * helpers (currently up to 9 subservices and 8 helpers).  The historical is
+ * simply that it started its life on OS/2 dreaming of conquring Windows next,
+ * so it kind of felt natural to have it all in one binary.
+ *
+ * Even if it's structured as a single binary, it is possible, by using command
+ * line options, to start each subservice as an individual process.
+ *
+ * Subservices:
+ *  - @subpage pg_vgsvc_timesync    "Time Synchronization"
+ *  - @subpage pg_vgsvc_vminfo      "VM Information"
+ *  - @subpage pg_vgsvc_vmstats     "VM Statistics"
+ *  - @subpage pg_vgsvc_gstctrl     "Guest Control"
+ *  - @subpage pg_vgsvc_pagesharing "Page Sharing"
+ *  - @subpage pg_vgsvc_memballoon  "Memory Balooning"
+ *  - @subpage pg_vgsvc_cpuhotplug  "CPU Hot-Plugging"
+ *  - @subpage pg_vgsvc_automount   "Shared Folder Automounting"
+ *  - @subpage pg_vgsvc_clipboard   "Clipboard (OS/2 only)"
+ *
+ * Now, since the service predates a lot of stuff, including RTGetOpt, we're
+ * currently doing our own version of argument parsing here, which is kind of
+ * stupid.  That will hopefully be cleaned up eventually.
+ */
 
 /*********************************************************************************************************************************

trunk/src/VBox/Additions/common/VBoxService/VBoxServiceControl.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_gstctrl VBoxService - Guest Control
+ *
+ * The Guest Control subservice helps implementing the IGuest APIs.
+ *
+ * The IGuest APIs provides means to manipulate (control) files, directories,
+ * symbolic links and processes within the guest.  Most of these means requires
+ * credentials of a guest OS user to operate, though some restricted ones
+ * operates directly as the VBoxService user (root / system service account).
+ *
+ * The current design is that a subprocess is spawned for handling operations as
+ * a given user.  This process is represented as IGuestSession in the API.  The
+ * subprocess will be spawned as the given use, giving up the privileges the
+ * parent subservice had.
+ *
+ * It will try handle as many of the operations directly from within the
+ * subprocess, but for more complicated things (or things that haven't yet been
+ * converted), it will spawn a helper process that does the actual work.
+ *
+ * These helpers are the typically modeled on similar unix core utilities, like
+ * mkdir, rm, rmdir, cat and so on.  The helper tools can also be launched
+ * directly from VBoxManage by the user by prepending the 'vbox_' prefix to the
+ * unix command.
+ *
  */
 

trunk/src/VBox/Additions/common/VBoxService/VBoxServicePageSharing.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_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.
+ *
+ * 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/VBoxServiceStats.cpp

@@ -16 +16 @@
  */
 
+/** @page pg_vgsvc_vmstats VBoxService - VM Statistics
+ *
+ * The VM statistics subservice helps out the performance collector API on the
+ * host side by providing metrics from inside the guest.
+ *
+ * See IPerformanceCollector, CollectorGuest and the "Guest/*" submetrics that
+ * gets registered by Machine::i_registerMetrics in Main.
+ */
 
 /*********************************************************************************************************************************

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

@@ -17 +17 @@
 
 
-/** @page pg_vboxservice_timesync       The Time Sync Service
+/** @page pg_vgsvc_timesync     VBoxService - The Time Sync Service
  *
  * The time sync service plays along with the Time Manager (TM) in the VMM
@@ -68 +68 @@
  *
  * It now boils down to these three (configuration) factors:
- *  -# g_TimesyncMinAdjust - The minimum drift we will ever bother with.
- *  -# g_TimesyncLatencyFactor - The factor we multiply the latency by to
+ *  -# g_TimeSyncMinAdjust - The minimum drift we will ever bother with.
+ *  -# g_TimeSyncLatencyFactor - The factor we multiply the latency by to
  *     calculate the dynamic minimum adjust factor.
- *  -# g_TimesyncMaxLatency - When to start discarding the data as utterly
+ *  -# g_TimeSyncMaxLatency - When to start discarding the data as utterly
  *     useless and take a rest (someone is too busy to give us good data).
  *  -# g_TimeSyncSetThreshold - The threshold at which we will just set the time

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

@@ -16 +16 @@
  */
 
+/** @page pg_vgsvc_vminfo VBoxService - VM Information
+ *
+ * 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.
+ *
+ *
+ * @section sec_vgsvc_vminfo_beacons    Beacons
+ *
+ * The subservice does not write properties unless there are changes.  So, in
+ * order for the host side to know that information is up to date despite an
+ * oldish timestamp we define a couple of values that are always updated and can
+ * reliably used to figure how old the information actually is.
+ *
+ * For the networking part "/VirtualBox/GuestInfo/Net/Count" is the value to
+ * watch out for.
+ *
+ * For the login part, it's possible that we intended to use
+ * "/VirtualBox/GuestInfo/OS/LoggedInUsers" for this, however it is not defined
+ * correctly and current does NOT work as a beacon.
+ *
+ */
 
 
@@ -886 +908 @@
         VGSvcError("Error writing logged in users count, rc=%Rrc\n", rc);
 
+/** @todo r=bird: What's this 'beacon' nonsense here?  It's _not_ defined with
+ *        the VGSVCPROPCACHE_FLAGS_ALWAYS_UPDATE flag set!!  */
     rc = VGSvcPropCacheUpdate(&g_VMInfoPropCache, g_pszPropCacheValNoLoggedInUsers, cUsersInList == 0 ? "true" : "false");
     if (RT_FAILURE(rc))