The API docs for the various vir$OBJECTGetConnect functions
contain a warning

  WARNING: When writing libvirt bindings in other languages, do
  not use this function.  Instead, store the connection and
  the domain object together.

There is no reason why language bindings should not use this
method, and indeed the Perl, Python, and Go bindings all use
these methods.

This warning was originally added back in

  commit 3edb4bc9
  Author: Daniel Veillard <veillard@redhat.com>
  Date:   Tue Jul 24 15:32:55 2007 +0000

    * libvirt.spec.in NEWS docs/* po/*: preparing release 0.3.1
    * src/libvirt.c python/generator.py: some cleanup and warnings
      from Richard W.M. Jones

IIUC, the rational was that these APIs do not need to be
directly exposed to the non-C language, as the language
can expose the same concept itself by storing the original
virConnectPtr object alongside the virDomainPtr.  There's
no reason to mandate such an approach though - it is valid
for languages to expose this directly if that suits their
needs better.
Signed-off-by: NDaniel P. Berrange <berrange@redhat.com>

It's obvious that unsigned long long is 64 bit and also our web page
generator would misplace the comment after the return value due to the
way it's parsing them.

Use ATTRIBUTE_FALLTHROUGH, introduced by commit
5d84f596, instead of comments to
indicate that the fall through is an intentional behavior.
Signed-off-by: NMarc Hartmayer <mhartmay@linux.vnet.ibm.com>
Reviewed-by: NBoris Fiuczynski <fiuczy@linux.vnet.ibm.com>
Reviewed-by: NBjoern Walk <bwalk@linux.vnet.ibm.com>

Allow starting the block-copy job for a persistent domain if a user
declares by using a flag that the job will not be recovered if the VM is
switched off while the job is active.

This allows to use the block-copy job with persistent VMs under the same
conditions as would apply to transient domains.

qemu requires that the topology equals to the maximum vcpu count.
Document this along with the API to set maximum vcpu count and the XML
element.

Resolves: https://bugzilla.redhat.com/show_bug.cgi?id=1426220

https://bugzilla.redhat.com/show_bug.cgi?id=1389313Signed-off-by: NJiri Denemark <jdenemar@redhat.com>

Management tools may want to check whether the threshold is still set if
they missed an event. Add the data to the bulk stats API where they can
also query the current backing size at the same time.

The new API can be used to configure the threshold when
VIR_DOMAIN_EVENT_ID_BLOCK_THRESHOLD should be fired.

This patch adds support and documentation
for the emulation_faults perf event.
Signed-off-by: NNitesh Konkar <nitkon12@linux.vnet.ibm.com>

This patch adds support and documentation
for the alignment_faults perf event.
Signed-off-by: NNitesh Konkar <nitkon12@linux.vnet.ibm.com>

This patch adds support and documentation
for the page_faults_maj perf event.
Signed-off-by: NNitesh Konkar <nitkon12@linux.vnet.ibm.com>

This patch adds support and documentation
for the page_faults_min perf event.
Signed-off-by: NNitesh Konkar <nitkon12@linux.vnet.ibm.com>

This patch adds support and documentation
for the cpu_migrations perf event.
Signed-off-by: NNitesh Konkar <nitkon12@linux.vnet.ibm.com>

This patch adds support and documentation
for the context_switches perf event.
Signed-off-by: NNitesh Konkar <nitkon12@linux.vnet.ibm.com>

This patch adds support and documentation
for the page_faults perf event.
Signed-off-by: NNitesh Konkar <nitkon12@linux.vnet.ibm.com>

This patch adds support and documentation for
the task_clock perf event.
Signed-off-by: NNitesh Konkar <nitkon12@linux.vnet.ibm.com>

This patch adds support and documentation for
the cpu_clock perf event.
Signed-off-by: NNitesh Konkar <nitkon12@linux.vnet.ibm.com>

Similarly to domainSetGuestVcpus this commit adds API which allows to
modify state of individual vcpus rather than just setting the count.

This allows to enable CPUs in specific guest NUMA nodes to achieve any
necessary configuration.

This reverts commit ae16c95f.

This patch adds support and documentation for
a generalized hardware cache event called cache_l1d
perf event.
Signed-off-by: NNitesh Konkar <nitkon12@linux.vnet.ibm.com>

This patch adds support and documentation for
the ref_cpu_cycles perf event.
Signed-off-by: NNitesh Konkar <nitkon12@linux.vnet.ibm.com>

This patch adds support and documentation for
the stalled_cycles_backend perf event.
Signed-off-by: NNitesh Konkar <nitkon12@linux.vnet.ibm.com>

This patch adds support and documentation
for the stalled_cycles_frontend perf event.
Signed-off-by: NNitesh Konkar <nitkon12@linux.vnet.ibm.com>

This patch adds support and documentation
for the bus_cycles perf event.
Signed-off-by: NNitesh Konkar <nitkon12@linux.vnet.ibm.com>

The virDomainSendProcessSignal method says the flags values
come from virDomainProcessSignalFlag, but this enum has
never existed. No flags are needed for this method.
Signed-off-by: NDaniel P. Berrange <berrange@redhat.com>

This patch adds support and documentation
for the branch_misses perf event.
Signed-off-by: NNitesh Konkar <nitkon12@linux.vnet.ibm.com>

Lost during merge of commit id '8546adf8' and '585ad00b'

With current perf framework, this patch adds support and documentation
for the branch_instructions perf event.
Signed-off-by: NNitesh Konkar <nitkon12@linux.vnet.ibm.com>

Adjust the spacing so that the code examples are display in the code/text
box rather than just as paragraph text.

Adjust the spacing a bit in order to generate 'cleaner' looking output.
This matches what virDomainMemoryStats does and it creates text/code boxes
in order to list each of the stats for each category.

Only the latest APIs are fully documented and the documentation of the
older variants (which are just limited versions of the new APIs anyway)
points to the newest APIs.
Signed-off-by: NJiri Denemark <jdenemar@redhat.com>

https://bugzilla.redhat.com/show_bug.cgi?id=1381714

Alter the descriptions to match what the cpu_cycles actually is

https://bugzilla.redhat.com/show_bug.cgi?id=1322717

During offline migration, no storage is copied. Nor disks, nor
NVRAM file, nor anything. We use qemu for that and because domain
is not running there's nobody to copy that for us.
We should document this to avoid confusing users.
Signed-off-by: NMichal Privoznik <mprivozn@redhat.com>

https://bugzilla.redhat.com/show_bug.cgi?id=1372613

Apparently, some management applications use the following code
pattern when waiting for a block job to finish:

  while (1) {
    virDomainGetBlockJobInfo(dom, disk, info, flags);

    if (info.cur == info.end)
        break;

    sleep(1);
  }

Problem with this approach is in its corner cases. In case of
QEMU, libvirt merely pass what has been reported on the monitor.
However, if the block job hasn't started yet, qemu reports cur ==
end == 0 which tricks mgmt apps into thinking job is complete.

The solution is to mangle cur/end values as described here [1].

1: https://www.redhat.com/archives/libvir-list/2016-September/msg00017.htmlSigned-off-by: NMichal Privoznik <mprivozn@redhat.com>

With current perf framework, this patch adds support and documentation
for more perf events, including cache misses, cache references, cpu cycles,
and instructions.
Signed-off-by: NQiaowei Ren <qiaowei.ren@intel.com>

This fixes commit 65bf0446 which introduced 'usable' stat.
Signed-off-by: NDerbyshev Dmitry <dderbyshev@virtuozzo.com>
Signed-off-by: NPavel Hrdina <phrdina@redhat.com>

QEMU reports timestamp along with other memory statistics, but this information is not saved into domain statistics.
It could be useful to determine if the data reported is fresh or not.
Balloon statistics are not reported in hrf, so no modifications are made in qemu_monitor_text.c.
Signed-off-by: NDerbyshev Dmitry <dderbyshev@virtuozzo.com>

'memtotal' in virtio drivers and qemu corresponds to 'available' in libvirt.
Because of that, 'stat-available-memory' is renamed into 'usable'.
Balloon statistics are not reported in hrf, so no modifications are made in qemu_monitor_text.c.
Signed-off-by: NDerbyshev Dmitry <dderbyshev@virtuozzo.com>

It may cause unwanted behaviour (of course, is there any wanted one for
that case?) so we should rather disable the possibility of doing so.

Resolves: https://bugzilla.redhat.com/show_bug.cgi?id=1320893Signed-off-by: NMartin Kletzander <mkletzan@redhat.com>