This part contains a lot of useful tips, but presenting all of them
at the same time obfuscated the central message which is, 'make check'
and 'make syntax-check' must pass after each patch in a series. Let's
move them to a separate page.
Signed-off-by: NAndrea Bolognani <abologna@redhat.com>
Reviewed-by: NDaniel P. Berrangé <berrange@redhat.com>

While it's good to have these rules written down for reference, they
apply exclusively to committers, who by definition are familiar with
the project and probably work on it daily, so there's no need to have
them front and center when a separate page will do.
Signed-off-by: NAndrea Bolognani <abologna@redhat.com>
Reviewed-by: NDaniel P. Berrangé <berrange@redhat.com>

This part describes entirely optional tooling, so it makes sense not
to have it advertised too prominently. Move it to a separate page.
Signed-off-by: NAndrea Bolognani <abologna@redhat.com>
Reviewed-by: NDaniel P. Berrangé <berrange@redhat.com>

Most new contributors are probably going to modify existing code rather
than introducing all-new programs and scripts, and even when the latter
happen they'll hopefully get a feel for which programming languages are
considered acceptable for the project by looking at what's already in
the repo. Make this part less prominent by moving it to a separate page.
Signed-off-by: NAndrea Bolognani <abologna@redhat.com>
Reviewed-by: NDaniel P. Berrangé <berrange@redhat.com>

This part represents the biggest chunk of the existing hacking.rst, and
despite that its utility is very limited because 'make syntax-check'
already guarantees most of the rules are followed over time.

Until the glorious day we finally codify our coding style completely
into a configuration for a tool such as clang-format and thus no longer
need a plain English description of it, move this part to a separate
page.
Signed-off-by: NAndrea Bolognani <abologna@redhat.com>
Reviewed-by: NDaniel P. Berrangé <berrange@redhat.com>

This part is very specific and doesn't quite fit into the "coding
style" section, so let's move it to its own page.
Signed-off-by: NAndrea Bolognani <abologna@redhat.com>
Reviewed-by: NDaniel P. Berrangé <berrange@redhat.com>

The conversion has been performed by using pandoc as a first pass,
and then tweaking the result manually until it looked satisfactory.
Signed-off-by: NAndrea Bolognani <abologna@redhat.com>
Reviewed-by: NDaniel P. Berrangé <berrange@redhat.com>

Signed-off-by: NDaniel P. Berrangé <berrange@redhat.com>

Libvirt uses GitHub as an automated read-only mirror. The goals were to
have a disaster recovery backup for libvirt.org, a way to make it easy
for people to clone their own private copy of libvirt Git, and finally
as a way to interact with apps like Travis.

The project description was set to a message telling people that we
don't respond to pull requests. This was quite a negative message to
potential contributors, and also did not give them any guidance about
the right way to submit to libvirt. Many also missed the description and
submitted issues or pull requests regardless.

It is possible to disable the issue tracker in GitHub, but there is no
way to disable merge requests. Disabling the issue tracker would also
leave the problem of users not being given any positive information
about where they should be reporting instead.

There is a fairly new 3rd party application built for GitHub that
provides a bot which auto-responds to both issues and merge requests,
closing and locking them, with a arbitrary comment:

   https://github.com/apps/repo-lockdown

This commit adds a suitable configuration file for libvirt, which
tries to give a positive response to user's issue/pullreq and guide
them to the desired contribution path on GitLab.
Reviewed-by: NAndrea Bolognani <abologna@redhat.com>
Reviewed-by: NPavel Hrdina <phrdina@redhat.com>
Reviewed-by: NEric Blake <eblake@redhat.com>
Signed-off-by: NDaniel P. Berrangé <berrange@redhat.com>

So far, libvirt generates the following path for automatic dumps:

  $autoDumpPath/$id-$shortName-$timestamp

where $autoDumpPath is where libvirt stores dumps of guests (e.g.
/var/lib/libvirt/qemu/dump), $id is domain ID and $shortName is
shortened version of domain name. So for instance, the generated
path may look something like this:

  /var/lib/libvirt/qemu/dump/1-QEMUGuest-2020-03-25-10:40:50

While in case of embed driver the following path would be
generated by default:

  $root/lib/libvirt/qemu/dump/1-QEMUGuest-2020-03-25-10:40:50

which is not clashing with other embed drivers, we allow users to
override the default and have all embed drivers use the same
prefix. This can create clashing paths. Fortunately, we can reuse
the approach for machined name generation
(v6.1.0-178-gc9bd08ee) and include part of hash of the root in
the generated path.
Signed-off-by: NMichal Privoznik <mprivozn@redhat.com>
Reviewed-by: NAndrea Bolognani <abologna@redhat.com>
Reviewed-by: NDaniel Henrique Barboza <danielhb413@gmail.com>
Reviewed-by: NDaniel P. Berrangé <berrange@redhat.com>

So far, libvirt generates the following path for memory:

  $memoryBackingDir/$id-$shortName/ram-nodeN

where $memoryBackingDir is the path where QEMU mmaps() memory for
the guest (e.g. /var/lib/libvirt/qemu/ram), $id is domain ID
and $shortName is shortened version of domain name. So for
instance, the generated path may look something like this:

  /var/lib/libvirt/qemu/ram/1-QEMUGuest/ram-node0

While in case of embed driver the following path would be
generated by default:

  $root/lib/qemu/ram/1-QEMUGuest/ram-node0

which is not clashing with other embed drivers, we allow users to
override the default and have all embed drivers use the same
prefix. This can create clashing paths. Fortunately, we can reuse
the approach for machined name generation
(v6.1.0-178-gc9bd08ee) and include part of hash of the root in
the generated path.

Note, the important change is in qemuGetMemoryBackingBasePath().
The rest is needed to pass driver around.
Signed-off-by: NMichal Privoznik <mprivozn@redhat.com>
Reviewed-by: NAndrea Bolognani <abologna@redhat.com>
Reviewed-by: NDaniel Henrique Barboza <danielhb413@gmail.com>
Reviewed-by: NDaniel P. Berrangé <berrange@redhat.com>

So far, libvirt generates the following path for hugepages:

  $mnt/libvirt/qemu/$id-$shortName

where $mnt is the mount point of hugetlbfs corresponding to
hugepages of desired size (e.g. /dev/hugepages), $id is domain ID
and $shortName is shortened version of domain name. So for
instance, the generated path may look something like this:

  /dev/hugepages/libvirt/qemu/1-QEMUGuest

But this won't work with embed driver really, because if there
are two instances of embed driver, and they both want to start a
domain with the same name and with hugepages, both drivers will
generate the same path which is not desired. Fortunately, we can
reuse the approach for machined name generation
(v6.1.0-178-gc9bd08ee) and include part of hash of the root in
the generated path.

Note, the important change is in qemuGetBaseHugepagePath(). The
rest is needed to pass driver around.
Signed-off-by: NMichal Privoznik <mprivozn@redhat.com>
Reviewed-by: NAndrea Bolognani <abologna@redhat.com>
Reviewed-by: NDaniel Henrique Barboza <danielhb413@gmail.com>
Reviewed-by: NDaniel P. Berrangé <berrange@redhat.com>

This reverts commit 06a19921.

What I haven't realized when writing this ^^ commit is that the
virQEMUDriver structure already stores the root directory path.
And since the pointer is immutable it can be accessed right from
the structure and thus there is no need to duplicate it in the
driver config.
Signed-off-by: NMichal Privoznik <mprivozn@redhat.com>
Reviewed-by: NAndrea Bolognani <abologna@redhat.com>
Reviewed-by: NDaniel Henrique Barboza <danielhb413@gmail.com>
Reviewed-by: NDaniel P. Berrangé <berrange@redhat.com>

The cfg->root is going away, therefore get the info right from
the driver structure.
Signed-off-by: NMichal Privoznik <mprivozn@redhat.com>
Reviewed-by: NAndrea Bolognani <abologna@redhat.com>
Reviewed-by: NDaniel Henrique Barboza <danielhb413@gmail.com>
Reviewed-by: NDaniel P. Berrangé <berrange@redhat.com>

The code that generates "qemu-embed-$hash" is going to be useful
in more places. Separate it out into a function.
Signed-off-by: NMichal Privoznik <mprivozn@redhat.com>
Reviewed-by: NAndrea Bolognani <abologna@redhat.com>
Reviewed-by: NDaniel Henrique Barboza <danielhb413@gmail.com>
Reviewed-by: NDaniel P. Berrangé <berrange@redhat.com>

The virDomainGenerateMachineName() function doesn't belong in
src/conf/ really, because it has nothing to do with domain XML
parsing. It landed there because of lack of better place in the
past. But now that we have src/hypervisor/ the function should
live there. At the same time, the function name is changed to
match new location.
Signed-off-by: NMichal Privoznik <mprivozn@redhat.com>
Reviewed-by: NAndrea Bolognani <abologna@redhat.com>
Reviewed-by: NDaniel Henrique Barboza <danielhb413@gmail.com>
Reviewed-by: NDaniel P. Berrangé <berrange@redhat.com>

Initially introduced in v3.10.0-rc1~172.

When generating a path for memory-backend-file or -mem-path, qemu
driver will use the following pattern:

  $memoryBackingDir/libvirt/qemu/$id-$shortName

where $memoryBackingDir defaults to /var/lib/libvirt/qemu/ram but
can be overridden in qemu.conf. Anyway, the "/libvirt/qemu/" part
looks redundant, because it's already contained in the default,
or creates unnecessary nesting if overridden in qemu.conf.
Signed-off-by: NMichal Privoznik <mprivozn@redhat.com>
Reviewed-by: NAndrea Bolognani <abologna@redhat.com>

Introduced in v1.2.17-rc1~121, the assumption was that the
driver->privileged is immutable at the time but it might change
in the future. Well, it did not ever since. It is still immutable
variable. Drop the needless accessor then.
Signed-off-by: NMichal Privoznik <mprivozn@redhat.com>
Reviewed-by: NAndrea Bolognani <abologna@redhat.com>

The virQEMUDriverConfigNew() accepts path to root directory for
embed mode as an argument. If the argument is not NULL it uses
the passed value as prefix for some internal paths (e.g.
cfg->libDir). If it is NULL though, it looks if the other
argument, @privileged is true or false and generates internal
paths accordingly. But when calling the function from the test
suite, instead of passing NULL for @root, an empty string is
passed. Fortunately, this doesn't create a problem because in
both problematic cases the generated paths are "fixed" to point
somewhere into build dir or the code which is tested doesn't
access them.
Signed-off-by: NMichal Privoznik <mprivozn@redhat.com>
Reviewed-by: NAndrea Bolognani <abologna@redhat.com>
Reviewed-by: NDaniel Henrique Barboza <danielhb413@gmail.com>
Reviewed-by: NDaniel P. Berrangé <berrange@redhat.com>

Signed-off-by: NSeeteena Thoufeek <s1seetee@linux.vnet.ibm.com>
Reviewed-by: NJán Tomko <jtomko@redhat.com>
Signed-off-by: NJán Tomko <jtomko@redhat.com>

Commit 54a401af split out DriverConfigInit from DriverConfigNew, but
then called it a bit late from libxlStateInitialize. The cfg is used in
libxlDriverConfigLoadFile and when uninitialized results in a crash.
Calling DriverConfigInit immediately after DriverConfigNew fixes the
crash.
Signed-off-by: NJim Fehlig <jfehlig@suse.com>
Reviewed-by: NErik Skultety <eskultet@redhat.com>
Reviewed-by: NJán Tomko <jtomko@redhat.com>

In the 'topology' element it is mentioned, regarding the sockets
value, "They refer to the total number of CPU sockets".

This is not accurate. What we're doing is calculating the number
of sockets per NUMA node, which can be checked in the current
implementation of virHostCPUGetInfoPopulateLinux(). Calculating
the total number of sockets would break the topology sanity
check nodes*sockets*cores*threads=online_cpus.

This documentation fix is important to avoid user confusion when
seeing the output of 'virsh capabilities' and expecting it to be
equal to the output of 'lscpu'. E.g in a Power 9 host this 'lscpu'
output:

Architecture:        ppc64le
Byte Order:          Little Endian
CPU(s):              160
On-line CPU(s) list: 0-159
Thread(s) per core:  4
Core(s) per socket:  20
Socket(s):           2
NUMA node(s):        2
Model:               2.2 (pvr 004e 1202)
Model name:          POWER9, altivec supported

And this XML output from virsh capabilities:

    <cpu>
      <arch>ppc64le</arch>
      <model>POWER9</model>
      <vendor>IBM</vendor>
      <topology sockets='1' dies='1' cores='20' threads='4'/>
      (...)
    </cpu>

Both are correct, as long as we mention in the Libvirt documentation
that 'sockets' in the topology element represents the number of sockets
per NUMA node.
Signed-off-by: NDaniel Henrique Barboza <danielhb413@gmail.com>
Reviewed-by: NMichal Privoznik <mprivozn@redhat.com>

Redeclared variables in script functions marked as local.
Variables `guest_running` and `guests_shutting_down` in the
functions 'guest_is_on` and `check_guests_shutdown` were
untouched, as the functions returned values in these
variables.
Signed-off-by: NPrathamesh Chavan <pc44800@gmail.com>
Reviewed-by: NMichal Privoznik <mprivozn@redhat.com>

Signed-off-by: NSeeteena Thoufeek <s1seetee@linux.vnet.ibm.com>
Signed-off-by: NMichal Privoznik <mprivozn@redhat.com>
Reviewed-by: NMichal Privoznik <mprivozn@redhat.com>
Reviewed-by: NDaniel Henrique Barboza <danielhb413@gmail.com>

This option prevents misbehaviours on guest if a qemu 9pfs export
contains multiple devices, due to the potential file ID collisions
this otherwise may cause.
Signed-off-by: NChristian Schoenebeck <qemu_oss@crudebyte.com>
Signed-off-by: NJán Tomko <jtomko@redhat.com>
Reviewed-by: NJán Tomko <jtomko@redhat.com>

Introduce new 'multidevs' option for filesystem.

  <filesystem type='mount' accessmode='mapped' multidevs='remap'>
    <source dir='/path'/>
    <target dir='mount_tag'>
  </filesystem>

This option prevents misbehaviours on guest if a qemu 9pfs export
contains multiple devices, due to the potential file ID collisions
this otherwise may cause.
Signed-off-by: NChristian Schoenebeck <qemu_oss@crudebyte.com>
Signed-off-by: NJán Tomko <jtomko@redhat.com>
Reviewed-by: NJán Tomko <jtomko@redhat.com>

The QEMU 9pfs 'multidevs' option exists since QEMU 4.2. Probe QEMU's
command line set though to check whether this option is really
available, and if yes enable this new QEMU_CAPS_FSDEV_MULTIDEVS
capability on libvirt side.
Signed-off-by: NChristian Schoenebeck <qemu_oss@crudebyte.com>
Signed-off-by: NJán Tomko <jtomko@redhat.com>
Reviewed-by: NJán Tomko <jtomko@redhat.com>

Now that all its helper functions are in qemu_validate.c, we can
move the function itself. The helpers can become static again since
they're all in the same file.
Signed-off-by: NDaniel Henrique Barboza <danielhb413@gmail.com>
Reviewed-by: NJán Tomko <jtomko@redhat.com>
Signed-off-by: NJán Tomko <jtomko@redhat.com>

This will allow to move qemuDomainDeviceDefValidate() itself in
the next patch in a cleaner way.
Signed-off-by: NDaniel Henrique Barboza <danielhb413@gmail.com>
Reviewed-by: NJán Tomko <jtomko@redhat.com>
Signed-off-by: NJán Tomko <jtomko@redhat.com>

Signed-off-by: NDaniel Henrique Barboza <danielhb413@gmail.com>
Reviewed-by: NJán Tomko <jtomko@redhat.com>
Signed-off-by: NJán Tomko <jtomko@redhat.com>

Signed-off-by: NDaniel Henrique Barboza <danielhb413@gmail.com>
Reviewed-by: NJán Tomko <jtomko@redhat.com>
Signed-off-by: NJán Tomko <jtomko@redhat.com>

Signed-off-by: NDaniel Henrique Barboza <danielhb413@gmail.com>
Reviewed-by: NJán Tomko <jtomko@redhat.com>
Signed-off-by: NJán Tomko <jtomko@redhat.com>

Move the function and all its static helper functions.
Signed-off-by: NDaniel Henrique Barboza <danielhb413@gmail.com>
Signed-off-by: NJán Tomko <jtomko@redhat.com>
Reviewed-by: NJán Tomko <jtomko@redhat.com>

This function will remain public due to its usage in qemublocktest.c
even after moving qemuDomainDeviceDefValidate(). The position of its
header in qemu_validate.h is no accident.
Signed-off-by: NDaniel Henrique Barboza <danielhb413@gmail.com>
Reviewed-by: NJán Tomko <jtomko@redhat.com>
Signed-off-by: NJán Tomko <jtomko@redhat.com>

Signed-off-by: NDaniel Henrique Barboza <danielhb413@gmail.com>
Reviewed-by: NJán Tomko <jtomko@redhat.com>
Signed-off-by: NJán Tomko <jtomko@redhat.com>

This function alone requires other 3 static functions to be
moved as well, thus let's move it in its own patch.
Signed-off-by: NDaniel Henrique Barboza <danielhb413@gmail.com>
Reviewed-by: NJán Tomko <jtomko@redhat.com>
Signed-off-by: NJán Tomko <jtomko@redhat.com>

qemuDomainChrDefValidate() has a lot of static helpers functions
that needed to be moved as well.

Other functions from qemuDomainDeviceDefValidate() that were
also moved:
- qemuValidateDomainSmartcardDef
- qemuValidateDomainRNGDef
- qemuValidateDomainRedirdevDef
- qemuValidateDomainWatchdogDef
Signed-off-by: NDaniel Henrique Barboza <danielhb413@gmail.com>
Reviewed-by: NJán Tomko <jtomko@redhat.com>
Signed-off-by: NJán Tomko <jtomko@redhat.com>

Signed-off-by: NDaniel Henrique Barboza <danielhb413@gmail.com>
Signed-off-by: NJán Tomko <jtomko@redhat.com>
Reviewed-by: NJán Tomko <jtomko@redhat.com>

The next big task is to move qemuDomainDeviceDefValidate() to
qemu_validation.c, which is a function that calls a lot of
other static helper functions. This patch starts it by moving
qemuDomainDeviceDefValidateAddress().
Signed-off-by: NDaniel Henrique Barboza <danielhb413@gmail.com>
Reviewed-by: NJán Tomko <jtomko@redhat.com>
Signed-off-by: NJán Tomko <jtomko@redhat.com>

Move the static functions qemuDomainValidateDef() uses, as well as
qemuDomainValidateDef() itself to qemu_validate.
Signed-off-by: NDaniel Henrique Barboza <danielhb413@gmail.com>
Signed-off-by: NJán Tomko <jtomko@redhat.com>
Reviewed-by: NJán Tomko <jtomko@redhat.com>