LTTng: Add developer documentation for virtual machine analysis

Change-Id: Ibbbd0680190c0a5992a7d088c4df54c460fa6341
Signed-off-by: Geneviève Bastien <gbastien+lttng@versatic.net>
Reviewed-on: https://git.eclipse.org/r/40090
Reviewed-by: Hudson CI
Reviewed-by: Matthew Khouzam <matthew.khouzam@ericsson.com>
Tested-by: Matthew Khouzam <matthew.khouzam@ericsson.com>

diff --git a/doc/org.eclipse.tracecompass.doc.dev/doc/Developer-Guide.mediawiki b/doc/org.eclipse.tracecompass.doc.dev/doc/Developer-Guide.mediawiki
index a287956fd10d1dafc824514bc08eb97e2b1ab555..e0ed0d4a1955bedbe4a842707fbefd9e7f86d8d5 100644 (file)
--- a/doc/org.eclipse.tracecompass.doc.dev/doc/Developer-Guide.mediawiki
+++ b/doc/org.eclipse.tracecompass.doc.dev/doc/Developer-Guide.mediawiki
@@ -4363,3 +4363,25 @@ View-specific markers can by added in sub-classes of ''AbstractTimeGraphView'' b
 * ''getViewMarkerCategories()'' returns a list of category names which will be displayed to the user, who can then enable or disable markers on a per-category basis.
 
 * ''getViewMarkerList()'' returns a list of markers instances of class ''IMarkerEvent'' for the given time range. The resolution can be used to limit the number of markers returned for the current zoom level, and the progress monitor can be checked for early cancellation of the marker computation.
+
+= Virtual Machine Analysis =
+
+Virtualized environment are becoming more popular and understanding them can be challenging as machines share resources (CPU, disks, memory, etc), but from their point of view, they are running on bare metal. Tracing all the machines (guests and hosts) in a virtualized environment allows information to be correlated between all the nodes to better understand the system. See the User documentation for more info on this analysis.
+
+The virtual machine analysis has been implemented in the following plugins:
+
+* '''org.eclipse.tracecompass.lttng2.kernel.core''' contains the virtual machine analysis itself, the model of the virtualized environment, as well as its implementation for different hypervisors.
+* '''org.eclipse.tracecompass.lttng2.kernel.ui''' contains the views for the analysis.
+
+== Adding support for an hypervisor ==
+
+Supporting a new hypervisor in Trace Compass requires implementing the model for this new hypervisor. The following sections will describe for each part of the model what has to be considered, what information we need to have, etc. Note that each hypervisor will require some work and investigation. The information might already be available as a single tracepoint for some, while other may require many tracepoints. It is also possible that some will require to add tracepoints, either to the kernel, or the hypervisor code itself, in which case a userspace trace (LTTng UST) might be necessary to get all the information.
+
+=== Virtual CPU analysis ===
+
+This analysis tracks the state of the virtual CPUs in conjunction with the physical CPU it is running on. For this, we need the following information:
+
+* A way to link a virtual CPU on a guest with a process on the host, such that it is possible to determine when the virtual CPU is preempted on the host. If trace data does not provide this information, some hypervisors have a command line option to dump that information. Manually feeding that information to the analysis is not supported now though.
+* A way to differentiate between hypervisor mode and normal mode for the virtual CPU. A virtual CPU usually runs within a process on the host, but sometimes that process may need to run hypervisor-specific code. That is called '''hypervisor mode'''. During that time, no code from the guest itself is run. Typically, the process is running on the host (not preempted), but from the guest's point of view, the virtual CPU should be preempted.
+
+A model implementation for a new hypervisor will need to implement class '''IVirtualMachineModel''', that can be found in package '''org.eclipse.tracecompass.internal.lttng2.kernel.core.analysis.vm.model'''. See the javadoc in the class itself for more information on what each method does.