[PATCH] qemu: Check usage count of qemu:override node
When is the only usage of the qemu namespace the entire section is mistakenly removed. Add check for use count. Signed-off-by: Justin Gatzen --- src/qemu/qemu_domain.c | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/qemu/qemu_domain.c b/src/qemu/qemu_domain.c index 95134a3570..00c209313b 100644 --- a/src/qemu/qemu_domain.c +++ b/src/qemu/qemu_domain.c @@ -3514,7 +3514,8 @@ qemuDomainDefNamespaceParse(xmlXPathContextPtr ctxt, if (nsdata->args || nsdata->num_env > 0 || nsdata->capsadd || nsdata->capsdel || -nsdata->deprecationBehavior) +nsdata->deprecationBehavior || +nsdata->ndeviceOverride > 0) *data = g_steal_pointer(); ret = 0; -- 2.35.1
Re: [PATCH v3 00/30] Add 'version' to other exported types
Hi, On Wed, Apr 20, 2022 at 09:07:49PM +0200, Victor Toso wrote: > Gitlab run of this series (fails with codestyle of do-not-commit > script). Actually, I fixed before sending. > https://gitlab.com/victortoso/libvirt/-/pipelines/520901763 Cheers, Victor signature.asc Description: PGP signature
[PATCH v3 24/30] scripts: apibuild: fix parsing block comments from typedef enum
Removed the TODO as we can rely to the serialize_typedef() the job to
report missing comments.
Signed-off-by: Victor Toso
---
scripts/apibuild.py | 8 +++-
1 file changed, 7 insertions(+), 1 deletion(-)
diff --git a/scripts/apibuild.py b/scripts/apibuild.py
index 19e897b1ba..ddc2fff7af 100755
--- a/scripts/apibuild.py
+++ b/scripts/apibuild.py
@@ -1145,6 +1145,12 @@ class CParser:
def parseTypedef(self, token):
if token is None:
return None
+
+# With typedef enum types, we can have comments parsed before the
+# enum themselves. The parsing of enum values does clear the
+# self.comment variable. So we store it here for later.
+typedef_comment = self.comment
+
token = self.parseType(token)
if token is None:
self.error("parsing typedef")
@@ -1168,7 +1174,7 @@ class CParser:
"struct", type)
base_type = "struct " + name
else:
-# TODO report missing or misformatted comments
+self.comment = typedef_comment
info = self.parseTypeComment(name, 1)
self.index_add(name, self.filename, not self.is_header,
"typedef", type, info)
--
2.35.1
[PATCH v3 10/30] docstring: typedef: libvirt:: Add 'Since version' metadata
Either create or append to existing docstring, the version (git tag)
that a given typedef was introduced in the format:
Since: v1.2.3
Signed-off-by: Victor Toso
---
include/libvirt/libvirt-domain-checkpoint.h | 34 +-
include/libvirt/libvirt-domain-snapshot.h | 40 +-
include/libvirt/libvirt-domain.h| 734 ++--
include/libvirt/libvirt-event.h | 3 +
include/libvirt/libvirt-host.h | 120 +++-
include/libvirt/libvirt-interface.h | 25 +-
include/libvirt/libvirt-network.h | 77 +-
include/libvirt/libvirt-nodedev.h | 22 +-
include/libvirt/libvirt-nwfilter.h | 25 +-
include/libvirt/libvirt-secret.h| 36 +-
include/libvirt/libvirt-storage.h | 133 +++-
include/libvirt/libvirt-stream.h| 18 +
include/libvirt/virterror.h | 19 +
13 files changed, 1212 insertions(+), 74 deletions(-)
diff --git a/include/libvirt/libvirt-domain-checkpoint.h
b/include/libvirt/libvirt-domain-checkpoint.h
index a59578b857..5a53717175 100644
--- a/include/libvirt/libvirt-domain-checkpoint.h
+++ b/include/libvirt/libvirt-domain-checkpoint.h
@@ -34,6 +34,9 @@
* a domain. A checkpoint is useful for tracking which portions of the
* domain disks have been altered since a point in time, but by itself does
* not allow reverting back to that point in time.
+ *
+ * Since: v5.2.0
+ *
*/
typedef struct _virDomainCheckpoint virDomainCheckpoint;
@@ -43,6 +46,9 @@ typedef struct _virDomainCheckpoint virDomainCheckpoint;
* A virDomainCheckpointPtr is pointer to a virDomainCheckpoint
* private structure, and is the type used to reference a domain
* checkpoint in the API.
+ *
+ * Since: v5.2.0
+ *
*/
typedef virDomainCheckpoint *virDomainCheckpointPtr;
@@ -50,6 +56,12 @@ const char
*virDomainCheckpointGetName(virDomainCheckpointPtr checkpoint);
virDomainPtr virDomainCheckpointGetDomain(virDomainCheckpointPtr checkpoint);
virConnectPtr virDomainCheckpointGetConnect(virDomainCheckpointPtr checkpoint);
+/**
+ * virDomainCheckpointCreateFlags:
+ *
+ * Since: v5.6.0
+ *
+ */
typedef enum {
VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE= (1 << 0), /* Restore or alter
metadata (Since:
v5.6.0) */
@@ -65,7 +77,12 @@ typedef enum {
virDomainCheckpointPtr virDomainCheckpointCreateXML(virDomainPtr domain,
const char *xmlDesc,
unsigned int flags);
-
+/**
+ * virDomainCheckpointXMLFlags:
+ *
+ * Since: v5.6.0
+ *
+ */
typedef enum {
VIR_DOMAIN_CHECKPOINT_XML_SECURE= (1 << 0), /* Include sensitive data
(Since: v5.6.0) */
VIR_DOMAIN_CHECKPOINT_XML_NO_DOMAIN = (1 << 1), /* Suppress
@@ -86,7 +103,11 @@ char *virDomainCheckpointGetXMLDesc(virDomainCheckpointPtr
checkpoint,
* flag (1<<0) depends on which function it is passed to; but serves
* to toggle the per-call default of whether the listing is shallow or
* recursive. Remaining bits come in groups; if all bits from a group
- * are 0, then that group is not used to filter results. */
+ * are 0, then that group is not used to filter results.
+ *
+ * Since: v5.6.0
+ *
+ */
typedef enum {
VIR_DOMAIN_CHECKPOINT_LIST_ROOTS = (1 << 0), /* Filter by checkpoints
with no parents, when
@@ -123,7 +144,14 @@ virDomainCheckpointPtr
virDomainCheckpointLookupByName(virDomainPtr domain,
virDomainCheckpointPtr virDomainCheckpointGetParent(virDomainCheckpointPtr
checkpoint,
unsigned int flags);
-/* Delete a checkpoint */
+/**
+ * virDomainCheckpointDeleteFlags:
+ *
+ * Delete a checkpoint
+ *
+ * Since: v5.6.0
+ *
+ */
typedef enum {
VIR_DOMAIN_CHECKPOINT_DELETE_CHILDREN = (1 << 0), /* Also delete
children (Since: v5.6.0) */
VIR_DOMAIN_CHECKPOINT_DELETE_METADATA_ONLY = (1 << 1), /* Delete just
metadata (Since: v5.6.0) */
diff --git a/include/libvirt/libvirt-domain-snapshot.h
b/include/libvirt/libvirt-domain-snapshot.h
index 5dffabb764..cdf82b29ce 100644
--- a/include/libvirt/libvirt-domain-snapshot.h
+++ b/include/libvirt/libvirt-domain-snapshot.h
@@ -34,6 +34,9 @@
* a domain. A snapshot captures the state of the domain at a point in
* time, with the intent that the guest can be reverted back to that
* state at a later time.
+ *
+ * Since: v0.8.0
+ *
*/
typedef struct _virDomainSnapshot virDomainSnapshot;
@@ -42,6 +45,9 @@ typedef struct _virDomainSnapshot virDomainSnapshot;
*
* A virDomainSnapshotPtr is pointer to a virDomainSnapshot private structure,
* and is the type used to reference a domain snapshot in the API.
+ *
+ * Since: v0.8.0
+ *
*/
typedef virDomainSnapshot *virDomainSnapshotPtr;
@@ -49,6 +55,12 @@ const char *virDomainSnapshotGetName(virDomainSnapshotPtr
snapshot);
[PATCH v3 20/30] docstring: Fix and append Since to virDomainDeviceModifyFlags
This commit is similar to "docs: Fix generated documentation of
virConnectListAllNodeDeviceFlags", check it out for more info.
Signed-off-by: Victor Toso
---
include/libvirt/libvirt-domain.h | 14 +++---
1 file changed, 7 insertions(+), 7 deletions(-)
diff --git a/include/libvirt/libvirt-domain.h b/include/libvirt/libvirt-domain.h
index 9199cc9ad3..27a680a907 100644
--- a/include/libvirt/libvirt-domain.h
+++ b/include/libvirt/libvirt-domain.h
@@ -2758,18 +2758,18 @@ int virDomainGetVcpus
(virDomainPtr domain,
/**
* virDomainDeviceModifyFlags:
*
- * Since: v1.0.0
+ * These flags may be bitwise-OR'd in.
+ *
+ * Since: v0.7.7
*
*/
typedef enum {
-/* See virDomainModificationImpact for these flags. (Since: v1.0.0) */
-VIR_DOMAIN_DEVICE_MODIFY_CURRENT = VIR_DOMAIN_AFFECT_CURRENT,
-VIR_DOMAIN_DEVICE_MODIFY_LIVE= VIR_DOMAIN_AFFECT_LIVE,
-VIR_DOMAIN_DEVICE_MODIFY_CONFIG = VIR_DOMAIN_AFFECT_CONFIG,
+VIR_DOMAIN_DEVICE_MODIFY_CURRENT = VIR_DOMAIN_AFFECT_CURRENT, /* See
virDomainModificationImpact (Since: v0.7.7) */
+VIR_DOMAIN_DEVICE_MODIFY_LIVE= VIR_DOMAIN_AFFECT_LIVE, /* (Since:
v0.7.7) */
+VIR_DOMAIN_DEVICE_MODIFY_CONFIG = VIR_DOMAIN_AFFECT_CONFIG, /* (Since:
v0.7.7) */
-/* Additionally, these flags may be bitwise-OR'd in. (Since: v1.0.0) */
VIR_DOMAIN_DEVICE_MODIFY_FORCE = (1 << 2), /* Forcibly modify device
- (ex. force eject a cdrom) */
+ (ex. force eject a cdrom)
(Since: v0.8.6) */
} virDomainDeviceModifyFlags;
int virDomainAttachDevice(virDomainPtr domain, const char *xml);
--
2.35.1
[PATCH v3 30/30] do-not-commit: script to validate output
A throw away script to validate that the generated XML has the
correct versions. It checks if $keyword is present in $git_tag and
also in the $next_git_tag but not in the $previous_git_tag.
Takes almost a minute to run, in my computer.
| python3 ./scripts/version-quest.py -i ./include/ -d ./build/docs/
| # libvirt has 2101 symbols
| # libvirt-qemu has 19 symbols
| # libvirt-lxc has 4 symbols
| # libvirt-admin has 63 symbols
| # Total of 2187 symbols checked
Signed-off-by: Victor Toso
---
scripts/version-quest.py | 190 +++
1 file changed, 190 insertions(+)
create mode 100644 scripts/version-quest.py
diff --git a/scripts/version-quest.py b/scripts/version-quest.py
new file mode 100644
index 00..01e5d28c59
--- /dev/null
+++ b/scripts/version-quest.py
@@ -0,0 +1,190 @@
+#!/usr/bin/env python3
+#
+# This is a simple utitly script to help check version of exported
+# types in XML built with scripts/apibuild.py
+#
+# See Copyright for the status of this software.
+#
+# victort...@redhat.com
+#
+
+import os
+import re
+import argparse
+
+tags = []
+includedir = ""
+xmldir = ""
+next_release = "v8.3.0"
+
+allowlist = {
+'virDomainSetBlockThreshold': '3.2.0',
+'virGetLastErrorMessage': '1.0.5.2',
+'virNodeDeviceCreate': '0.5.0',
+'virAdmClientClose': '1.3.5',
+'virAdmClientFree': '1.3.5',
+'virAdmClientGetID': '1.3.5',
+'virAdmClientGetInfo': '1.3.5',
+'virAdmClientGetTimestamp': '1.3.5',
+'virAdmClientGetTransport': '1.3.5',
+'virAdmConnectClose': '1.2.17',
+'virAdmConnectGetLibVersion': '1.3.1',
+'virAdmConnectGetURI': '1.3.1',
+'virAdmConnectIsAlive': '1.3.1',
+'virAdmConnectListServers': '1.3.2',
+'virAdmConnectLookupServer': '1.3.3',
+'virAdmConnectOpen': '1.2.17',
+'virAdmConnectRef': '1.2.17',
+'virAdmConnectRegisterCloseCallback': '1.3.1',
+'virAdmConnectUnregisterCloseCallback': '1.3.1',
+'virAdmGetVersion': '1.3.0',
+'virAdmServerFree': '1.3.2',
+'virAdmServerGetClientLimits': '1.3.5',
+'virAdmServerGetName': '1.3.2',
+'virAdmServerGetThreadPoolParameters': '1.3.4',
+'virAdmServerListClients': '1.3.5',
+'virAdmServerLookupClient': '1.3.5',
+'virAdmServerSetClientLimits': '1.3.5',
+'virAdmServerSetThreadPoolParameters': '1.3.4',
+'virAdmServerUpdateTlsFiles': '6.2.0',
+'virConnectFindStoragePoolSources': '0.4.6',
+'virConnectNumOfDefinedDomains': '0.1.6',
+'virConnectOpenAuth': '0.4.1',
+'virDomainBlockPeek': '0.4.4',
+'virDomainMemoryPeek': '0.4.4',
+'virNetworkUpdate': '1.0.0',
+'virConnectClose': '0.0.1',
+'virConnectGetType': '0.0.1',
+'virConnectGetVersion': '0.0.1',
+'virConnectListDomains': '0.0.1',
+'virConnectNumOfDomains': '0.0.1',
+'virConnectOpen': '0.0.1',
+'virConnectOpenReadOnly': '0.0.1',
+'virDomainCreateLinux': '0.0.1',
+'virDomainDestroy': '0.0.1',
+'virDomainFree': '0.0.1',
+'virDomainGetID': '0.0.1',
+'virDomainGetInfo': '0.0.1',
+'virDomainGetMaxMemory': '0.0.1',
+'virDomainGetName': '0.0.1',
+'virDomainGetOSType': '0.0.1',
+'virDomainGetXMLDesc': '0.0.1',
+'virDomainLookupByID': '0.0.1',
+'virDomainLookupByName': '0.0.1',
+'virDomainRestore': '0.0.2',
+'virDomainResume': '0.0.1',
+'virDomainSave': '0.0.2',
+'virDomainSetMaxMemory': '0.0.1',
+'virDomainShutdown': '0.0.1',
+'virDomainSuspend': '0.0.1',
+'virGetVersion': '0.0.1',
+}
+
+
+def get_symbols(xmlpath: str):
+symbols = []
+expression = "<(.*?) name='(.*?)'.*version='(.*?)'"
+with open(xmlpath) as file:
+for line in file:
+r = re.search(expression, line)
+if r is not None:
+symbols.append(r.groups())
+
+return symbols
+
+
+def find_version(symbol, start_version):
+index = start_version == "" and -1 or tags.index(start_version)
+for i in range(index + 1, len(tags)):
+if git_check_symbol(symbol, tags[i]):
+return tags[i]
+
+assert False
+
+
+def get_tags_array() -> list[str]:
+# We will be looking symbols at released tags. Only vx.y.z are
+# interesting to us.
+k = os.popen("git tag --list 'v*' | grep -v 'rc' | sort -V")
+alltags = k.read().split()
+return alltags
+
+
+def git_check_symbol(symbol, version, full=False) -> bool:
+path = full and "" or includedir
+s = os.system(f"git grep -rqw {symbol} {version} {path}")
+return os.waitstatus_to_exitcode(s) == 0
+
+
+def check_symbol(symbol, xml_version) -> (bool, str):
+# For functions that were released with wrong sym version
+if symbol in allowlist:
+docversion = f"v{allowlist[symbol]}"
+if docversion == xml_version:
+return (False, f"{symbol} allowlist versions match: {xml_version}")
+
+if not git_check_symbol(symbol, docversion, True):
+version = find_version(symbol, docversion)
+return
[PATCH v3 27/30] scripts: apibuild: parse 'Since' for functions
This patch adds 'version' parameter to generated XML API for functions
and functypes.
The 'version' metadata has been added with e0e0bf6628 by parsing .syms
files. This commit does not override that but it will warn if there is
not 'Since' metadata with new additions.
There is not clear benefit for keeping both. For now, I've added a
warning in case there is a mismatch between the version provided by
.syms and docstring.
Signed-off-by: Victor Toso
---
scripts/apibuild.py | 126 +++-
1 file changed, 113 insertions(+), 13 deletions(-)
diff --git a/scripts/apibuild.py b/scripts/apibuild.py
index b77eea0624..ec10931151 100755
--- a/scripts/apibuild.py
+++ b/scripts/apibuild.py
@@ -111,6 +111,73 @@ ignored_functions = {
"virErrorCopyNew": "private",
}
+# The version in the .sym file might differnt from
+# the real version that the function was introduced.
+# This dict's value is the correct version, as it should
+# be in the docstrings.
+ignored_function_versions = {
+'virDomainSetBlockThreshold': '3.2.0',
+'virGetLastErrorMessage': '1.0.5.2',
+'virNodeDeviceCreate': '0.5.0',
+'virAdmClientClose': '1.3.5',
+'virAdmClientFree': '1.3.5',
+'virAdmClientGetID': '1.3.5',
+'virAdmClientGetInfo': '1.3.5',
+'virAdmClientGetTimestamp': '1.3.5',
+'virAdmClientGetTransport': '1.3.5',
+'virAdmConnectClose': '1.2.17',
+'virAdmConnectGetLibVersion': '1.3.1',
+'virAdmConnectGetURI': '1.3.1',
+'virAdmConnectIsAlive': '1.3.1',
+'virAdmConnectListServers': '1.3.2',
+'virAdmConnectLookupServer': '1.3.3',
+'virAdmConnectOpen': '1.2.17',
+'virAdmConnectRef': '1.2.17',
+'virAdmConnectRegisterCloseCallback': '1.3.1',
+'virAdmConnectUnregisterCloseCallback': '1.3.1',
+'virAdmGetVersion': '1.3.0',
+'virAdmServerFree': '1.3.2',
+'virAdmServerGetClientLimits': '1.3.5',
+'virAdmServerGetName': '1.3.2',
+'virAdmServerGetThreadPoolParameters': '1.3.4',
+'virAdmServerListClients': '1.3.5',
+'virAdmServerLookupClient': '1.3.5',
+'virAdmServerSetClientLimits': '1.3.5',
+'virAdmServerSetThreadPoolParameters': '1.3.4',
+'virAdmServerUpdateTlsFiles': '6.2.0',
+'virConnectFindStoragePoolSources': '0.4.6',
+'virConnectNumOfDefinedDomains': '0.1.6',
+'virConnectOpenAuth': '0.4.1',
+'virDomainBlockPeek': '0.4.4',
+'virDomainMemoryPeek': '0.4.4',
+'virNetworkUpdate': '1.0.0',
+'virConnectClose': '0.0.1',
+'virConnectGetType': '0.0.1',
+'virConnectGetVersion': '0.0.1',
+'virConnectListDomains': '0.0.1',
+'virConnectNumOfDomains': '0.0.1',
+'virConnectOpen': '0.0.1',
+'virConnectOpenReadOnly': '0.0.1',
+'virDomainCreateLinux': '0.0.1',
+'virDomainDestroy': '0.0.1',
+'virDomainFree': '0.0.1',
+'virDomainGetID': '0.0.1',
+'virDomainGetInfo': '0.0.1',
+'virDomainGetMaxMemory': '0.0.1',
+'virDomainGetName': '0.0.1',
+'virDomainGetOSType': '0.0.1',
+'virDomainGetXMLDesc': '0.0.1',
+'virDomainLookupByID': '0.0.1',
+'virDomainLookupByName': '0.0.1',
+'virDomainRestore': '0.0.2',
+'virDomainResume': '0.0.1',
+'virDomainSave': '0.0.2',
+'virDomainSetMaxMemory': '0.0.1',
+'virDomainShutdown': '0.0.1',
+'virDomainSuspend': '0.0.1',
+'virGetVersion': '0.0.1',
+}
+
ignored_macros = {
"_virSchedParameter": "backward compatibility macro for virTypedParameter",
"_virBlkioParameter": "backward compatibility macro for virTypedParameter",
@@ -2185,9 +2252,10 @@ class docBuilder:
self.scanVersions()
# Fetch tags from the comment. Only 'Since' supported at the moment.
-# Return the tags and the original comment without the tags.
-def retrieve_comment_tags(self, name: str, comment: str
- ) -> (str, str):
+# For functions, since tags are on Return comments.
+# Return the tags and the original comments, but without the tags.
+def retrieve_comment_tags(self, name: str, comment: str, return_comment=""
+ ) -> (str, str, str):
since = ""
if comment is not None:
comment_match = re.search(r"\(?Since: v?(\d+\.\d+\.\d+\.?\d?)\)?",
@@ -2200,9 +2268,20 @@ class docBuilder:
# Only the version
since = comment_match.group(1)
+if since == "" and return_comment is not None:
+return_match = re.search(r"\(?Since: v?(\d+\.\d+\.\d+\.?\d?)\)?",
+ return_comment)
+if return_match:
+# Remove Since tag from the comment
+(start, end) = return_match.span()
+return_comment = return_comment[:start] + return_comment[end:]
+return_comment = return_comment.strip()
+# Only the version
+since = return_match.group(1)
+
if since == "":
self.warning("Missing 'Since' tag
[PATCH v3 16/30] docstring: function: admin: Add 'Since version' metadata
Either create or append to existing docstring, the version (git tag)
that a given function was introduced in the format:
Since: v1.2.3
Signed-off-by: Victor Toso
---
include/libvirt/libvirt-admin.h | 3 ++
src/admin/libvirt-admin.c | 93 +
2 files changed, 96 insertions(+)
diff --git a/include/libvirt/libvirt-admin.h b/include/libvirt/libvirt-admin.h
index c73cf6e7da..5945fc172c 100644
--- a/include/libvirt/libvirt-admin.h
+++ b/include/libvirt/libvirt-admin.h
@@ -126,6 +126,9 @@ int virAdmConnectGetLibVersion(virAdmConnectPtr conn,
* @opaque: opaque client data
*
* A callback to be registered, in case a connection was closed.
+ *
+ * Since: v1.3.1
+ *
*/
typedef void (*virAdmConnectCloseFunc)(virAdmConnectPtr conn,
int reason,
diff --git a/src/admin/libvirt-admin.c b/src/admin/libvirt-admin.c
index 01546a7bc2..35470c866e 100644
--- a/src/admin/libvirt-admin.c
+++ b/src/admin/libvirt-admin.c
@@ -84,6 +84,9 @@ virAdmGlobalInit(void)
* necessary for the application to call virAdmInitialize.
*
* Returns 0 in case of success, -1 in case of error
+ *
+ * Since: v2.0.0
+ *
*/
int
virAdmInitialize(void)
@@ -200,6 +203,9 @@ virAdmGetDefaultURI(virConf *conf, char **uristr)
* Opens connection to admin interface of the daemon.
*
* Returns @virAdmConnectPtr object or NULL on error
+ *
+ * Since: v1.2.17
+ *
*/
virAdmConnectPtr
virAdmConnectOpen(const char *name, unsigned int flags)
@@ -284,6 +290,9 @@ virAdmConnectOpen(const char *name, unsigned int flags)
* some other object still has a temporary reference to the connection, but the
* application should not try to further use a connection after the
* virAdmConnectClose that matches the initial open.
+ *
+ * Since: v1.2.17
+ *
*/
int
virAdmConnectClose(virAdmConnectPtr conn)
@@ -319,6 +328,9 @@ virAdmConnectClose(virAdmConnectPtr conn)
* would increment the reference count.
*
* Returns 0 in case of success, -1 in case of failure
+ *
+ * Since: v1.2.17
+ *
*/
int
virAdmConnectRef(virAdmConnectPtr conn)
@@ -346,6 +358,9 @@ virAdmConnectRef(virAdmConnectPtr conn)
* instead.
*
* Returns 0 on success, -1 in case of an error.
+ *
+ * Since: v1.3.0
+ *
*/
int
virAdmGetVersion(unsigned long long *libVer)
@@ -377,6 +392,9 @@ virAdmGetVersion(unsigned long long *libVer)
*
* Returns 1, if the connection is alive, 0 if there isn't an existing
* connection at all or the channel has already been closed, or -1 on error.
+ *
+ * Since: v1.3.1
+ *
*/
int
virAdmConnectIsAlive(virAdmConnectPtr conn)
@@ -411,6 +429,9 @@ virAdmConnectIsAlive(virAdmConnectPtr conn)
*
* Returns an URI string related to the connection or NULL in case of an error.
* Caller is responsible for freeing the string.
+ *
+ * Since: v1.3.1
+ *
*/
char *
virAdmConnectGetURI(virAdmConnectPtr conn)
@@ -445,6 +466,9 @@ virAdmConnectGetURI(virAdmConnectPtr conn)
* context.
*
* Returns 0 on success, -1 on error
+ *
+ * Since: v1.3.1
+ *
*/
int virAdmConnectRegisterCloseCallback(virAdmConnectPtr conn,
virAdmConnectCloseFunc cb,
@@ -498,6 +522,9 @@ int virAdmConnectRegisterCloseCallback(virAdmConnectPtr
conn,
* registration, it will be invoked.
*
* Returns 0 on success, -1 on error
+ *
+ * Since: v1.3.1
+ *
*/
int virAdmConnectUnregisterCloseCallback(virAdmConnectPtr conn,
virAdmConnectCloseFunc cb)
@@ -528,6 +555,9 @@ int virAdmConnectUnregisterCloseCallback(virAdmConnectPtr
conn,
* major * 1,000,000 + minor * 1,000 + release.
*
* Returns 0 on success, -1 on failure and @libVer follows this format:
+ *
+ * Since: v1.3.1
+ *
*/
int virAdmConnectGetLibVersion(virAdmConnectPtr conn,
unsigned long long *libVer)
@@ -556,6 +586,9 @@ int virAdmConnectGetLibVersion(virAdmConnectPtr conn,
*
* Returns a pointer to the name or NULL. The string doesn't need to be
* deallocated since its lifetime will be the same as the server object.
+ *
+ * Since: v1.3.2
+ *
*/
const char *
virAdmServerGetName(virAdmServerPtr srv)
@@ -576,6 +609,9 @@ virAdmServerGetName(virAdmServerPtr srv)
* The data structure is freed and should not be used thereafter.
*
* Returns 0 on success, -1 on failure.
+ *
+ * Since: v1.3.2
+ *
*/
int virAdmServerFree(virAdmServerPtr srv)
{
@@ -599,6 +635,9 @@ int virAdmServerFree(virAdmServerPtr srv)
* Get client's unique numeric ID.
*
* Returns numeric value used for client's ID or -1 in case of an error.
+ *
+ * Since: v1.3.5
+ *
*/
unsigned long long
virAdmClientGetID(virAdmClientPtr client)
@@ -622,6 +661,9 @@ virAdmClientGetID(virAdmClientPtr client)
* Returns client's connection timestamp (seconds from epoch in UTC) or 0
* (epoch time) if libvirt doesn't have any information about client's
* connection time, or -1 in case of an error.
+ *
+ * Since: v1.3.5
+ *
*/
long long
[PATCH v3 29/30] scripts: apibuild: add parsing variable's comments
scripts/apibuild.py did not consider exporting external variable's
comments into the XML API. This commits fixes that.
Noe that the way that CParser is designed, it is currently possible to
lose a parsed comment when parsing other fields as self.comment in
several places. I've added a comment to highlight this.
Signed-off-by: Victor Toso
---
scripts/apibuild.py | 22 --
1 file changed, 16 insertions(+), 6 deletions(-)
diff --git a/scripts/apibuild.py b/scripts/apibuild.py
index 151eba37e6..9bdea648d4 100755
--- a/scripts/apibuild.py
+++ b/scripts/apibuild.py
@@ -1997,10 +1997,14 @@ class CParser:
if token is None or token[0] != 'name':
return token
+variable_comment = None
if token[1] == 'typedef':
token = self.token()
return self.parseTypedef(token)
else:
+# Store block of comment that might be from variable as
+# the code uses self.comment a lot and it would lose it.
+variable_comment = self.cleanup_code_comment(self.comment)
token = self.parseType(token)
type_orig = self.type
if token is None or token[0] != "name":
@@ -2046,8 +2050,10 @@ class CParser:
not self.is_header, "struct",
self.struct_fields)
else:
+# Just to use the cleanupComment function.
+info = (type, variable_comment)
self.index_add(self.name, self.filename,
- not self.is_header, "variable", type)
+ not self.is_header, "variable", info)
break
elif token[1] == "(":
token = self.token()
@@ -2424,12 +2430,16 @@ class docBuilder:
def serialize_variable(self, output, name):
id = self.idx.variables[name]
-if id.info is not None:
-output.write("\n" % (
-name, self.modulename_file(id.header), id.info))
+(type, comment) = id.info
+(since, comment, _) = self.retrieve_comment_tags(name, comment)
+version_tag = len(since) > 0 and f" version='{since}'" or ""
+output.write("\n")
else:
-output.write("\n" % (
-name, self.modulename_file(id.header)))
+output.write(">\n \n" % (comment))
+output.write("\n")
def serialize_function(self, output, name):
id = self.idx.functions[name]
--
2.35.1
[PATCH v3 28/30] scripts: apibuild: factor out comment cleaning
So we can use for comments that are being hold in helper variables.
Signed-off-by: Victor Toso
---
scripts/apibuild.py | 15 +--
1 file changed, 9 insertions(+), 6 deletions(-)
diff --git a/scripts/apibuild.py b/scripts/apibuild.py
index ec10931151..151eba37e6 100755
--- a/scripts/apibuild.py
+++ b/scripts/apibuild.py
@@ -789,15 +789,18 @@ class CParser:
line = line.replace('*', '', 1)
return line
-def cleanupComment(self):
-if not isinstance(self.comment, str):
-return
-# remove the leading * on multi-line comments
-lines = self.comment.splitlines(True)
+def cleanup_code_comment(self, comment: str) -> str:
+if not isinstance(self.comment, str) or comment == "":
+return ""
+
+lines = comment.splitlines(True)
com = ""
for line in lines:
com = com + self.strip_lead_star(line)
-self.comment = com.strip()
+return com.strip()
+
+def cleanupComment(self):
+self.comment = self.cleanup_code_comment(self.comment)
def parseComment(self, token):
com = token[1]
--
2.35.1
[PATCH v3 26/30] scripts: apibuild: parse 'Since' for macros
This patch adds 'version' parameter to the generated XML API for
macros
It'll require, for new additions, to add a comment with the version
that the macro was added. An example bellow of code diff and
the change in the generated XML.
Note that the Since tag is removed from the comment as there is a
proper field for it in the XML.
Signed-off-by: Victor Toso
---
scripts/apibuild.py | 10 +++---
1 file changed, 7 insertions(+), 3 deletions(-)
diff --git a/scripts/apibuild.py b/scripts/apibuild.py
index 24ca98bd1c..b77eea0624 100755
--- a/scripts/apibuild.py
+++ b/scripts/apibuild.py
@@ -2267,11 +2267,15 @@ class docBuilder:
output.write(" string='%s'" % strValue)
else:
output.write(" raw='%s'" % escape(rawValue))
+
+(since, comment) = self.retrieve_comment_tags(name, desc)
+if len(since) > 0:
+output.write(" version='%s'" % escape(since))
output.write(">\n")
-if desc is not None and desc != "":
-output.write(" \n" % (desc))
-self.indexString(name, desc)
+if comment is not None and comment != "":
+output.write(" \n" % (comment))
+self.indexString(name, comment)
for arg in args:
(name, desc) = arg
if desc is not None and desc != "":
--
2.35.1
[PATCH v3 25/30] scripts: apibuild: parse 'Since' for typedefs
This patch adds 'version' parameter to the generated XML API for
typedefs
It'll require, for new additions, to add a comment with the version
that the typedef value was added. An example bellow of code diff and
the change in the generated XML.
Note that the Since tag is removed from the comment as there is a
proper field for it in the XML.
Signed-off-by: Victor Toso
---
scripts/apibuild.py | 15 ---
1 file changed, 8 insertions(+), 7 deletions(-)
diff --git a/scripts/apibuild.py b/scripts/apibuild.py
index ddc2fff7af..24ca98bd1c 100755
--- a/scripts/apibuild.py
+++ b/scripts/apibuild.py
@@ -2298,9 +2298,11 @@ class docBuilder:
def serialize_typedef(self, output, name):
id = self.idx.typedefs[name]
+(since, comment) = self.retrieve_comment_tags(name, id.extra)
+version_tag = len(since) > 0 and f" version='{since}'" or ""
if id.info[0:7] == 'struct ':
-output.write("\n")
else:
-output.write("\n \n" %
(desc))
+if comment is not None and comment != "":
+output.write(">\n \n" %
(comment))
output.write("\n")
else:
output.write("/>\n")
--
2.35.1
[PATCH v3 23/30] scripts: apibuild: parse 'Since' version for enums
This patch adds 'version' parameter to the generated XML API for
enums.
It'll require, for new additions, to add a comment with the version
that the enum value was added.
Note that the Since tag is removed from the comment as there is a
proper field for it in the XML.
Signed-off-by: Victor Toso
---
scripts/apibuild.py | 30 +-
1 file changed, 29 insertions(+), 1 deletion(-)
diff --git a/scripts/apibuild.py b/scripts/apibuild.py
index bdd3077c48..19e897b1ba 100755
--- a/scripts/apibuild.py
+++ b/scripts/apibuild.py
@@ -2178,6 +2178,26 @@ class docBuilder:
self.scanModules()
self.scanVersions()
+# Fetch tags from the comment. Only 'Since' supported at the moment.
+# Return the tags and the original comment without the tags.
+def retrieve_comment_tags(self, name: str, comment: str
+ ) -> (str, str):
+since = ""
+if comment is not None:
+comment_match = re.search(r"\(?Since: v?(\d+\.\d+\.\d+\.?\d?)\)?",
+ comment)
+if comment_match:
+# Remove Since tag from the comment
+(start, end) = comment_match.span()
+comment = comment[:start] + comment[end:]
+comment = comment.strip()
+# Only the version
+since = comment_match.group(1)
+
+if since == "":
+self.warning("Missing 'Since' tag for: " + name)
+return (since, comment)
+
def modulename_file(self, file):
module = os.path.basename(file)
if module[-2:] == '.h':
@@ -2211,7 +2231,15 @@ class docBuilder:
if info[2] is not None and info[2] != '':
output.write(" type='%s'" % info[2])
if info[1] is not None and info[1] != '':
-output.write(" info='%s'" % escape(info[1]))
+# Search for 'Since' version tag
+(since, comment) = self.retrieve_comment_tags(name, info[1])
+if len(since) > 0:
+output.write(" version='%s'" % escape(since))
+if len(comment) > 0:
+output.write(" info='%s'" % escape(comment))
+else:
+self.warning("Missing docstring for enum: " + name)
+
output.write("/>\n")
def serialize_macro(self, output, name):
--
2.35.1
[PATCH v3 22/30] docstring: Fix and append Since to virDomainVcpuFlags
This commit is similar to "docs: Fix generated documentation of
virConnectListAllNodeDeviceFlags", check it out for more info.
Signed-off-by: Victor Toso
---
include/libvirt/libvirt-domain.h | 19 +--
1 file changed, 9 insertions(+), 10 deletions(-)
diff --git a/include/libvirt/libvirt-domain.h b/include/libvirt/libvirt-domain.h
index 67cbc0d08e..689a17a223 100644
--- a/include/libvirt/libvirt-domain.h
+++ b/include/libvirt/libvirt-domain.h
@@ -2491,20 +2491,19 @@ typedef virVcpuInfo *virVcpuInfoPtr;
* virDomainVcpuFlags:
*
* Flags for controlling virtual CPU hot-plugging.
+ * These flags may be bitwise-OR'd in.
*
- * Since: v1.0.0
+ * Since: v0.8.5
*
*/
typedef enum {
-/* See virDomainModificationImpact for these flags. (Since: v1.0.0) */
-VIR_DOMAIN_VCPU_CURRENT = VIR_DOMAIN_AFFECT_CURRENT,
-VIR_DOMAIN_VCPU_LIVE= VIR_DOMAIN_AFFECT_LIVE,
-VIR_DOMAIN_VCPU_CONFIG = VIR_DOMAIN_AFFECT_CONFIG,
-
-/* Additionally, these flags may be bitwise-OR'd in. (Since: v1.0.0) */
-VIR_DOMAIN_VCPU_MAXIMUM = (1 << 2), /* Max rather than current count
(Since: v1.1.0) */
-VIR_DOMAIN_VCPU_GUEST = (1 << 3), /* Modify state of the cpu in the
guest (Since: v2.4.0) */
-VIR_DOMAIN_VCPU_HOTPLUGGABLE = (1 << 4), /* Make vcpus added
hot(un)pluggable */
+VIR_DOMAIN_VCPU_CURRENT = VIR_DOMAIN_AFFECT_CURRENT, /* See
virDomainModificationImpact (Since: v0.9.4) */
+VIR_DOMAIN_VCPU_LIVE= VIR_DOMAIN_AFFECT_LIVE, /* See
virDomainModificationImpact (Since: v0.8.5) */
+VIR_DOMAIN_VCPU_CONFIG = VIR_DOMAIN_AFFECT_CONFIG, /* See
virDomainModificationImpact (Since: v0.8.5) */
+
+VIR_DOMAIN_VCPU_MAXIMUM = (1 << 2), /* Max rather than current count
(Since: v0.8.5) */
+VIR_DOMAIN_VCPU_GUEST = (1 << 3), /* Modify state of the cpu in the
guest (Since: v1.1.0) */
+VIR_DOMAIN_VCPU_HOTPLUGGABLE = (1 << 4), /* Make vcpus added
hot(un)pluggable (Since: v2.4.0) */
} virDomainVcpuFlags;
int virDomainSetVcpus (virDomainPtr domain,
--
2.35.1
[PATCH v3 15/30] docstring: function: lxc: Add 'Since version' metadata
Either create or append to existing docstring, the version (git tag)
that a given function was introduced in the format:
Since: v1.2.3
Signed-off-by: Victor Toso
---
src/libvirt-lxc.c | 12
1 file changed, 12 insertions(+)
diff --git a/src/libvirt-lxc.c b/src/libvirt-lxc.c
index 2a271b74f0..14a2f2a6ec 100644
--- a/src/libvirt-lxc.c
+++ b/src/libvirt-lxc.c
@@ -59,6 +59,9 @@ VIR_LOG_INIT("libvirt-lxc");
* the setns() system call.
*
* Returns the number of opened file descriptors, or -1 on error
+ *
+ * Since: v1.0.2
+ *
*/
int
virDomainLxcOpenNamespace(virDomainPtr domain,
@@ -115,6 +118,9 @@ virDomainLxcOpenNamespace(virDomainPtr domain,
* the caller to switch back to its current namespace later
*
* Returns 0 on success, -1 on error
+ *
+ * Since: v1.0.2
+ *
*/
int
virDomainLxcEnterNamespace(virDomainPtr domain,
@@ -182,6 +188,9 @@ virDomainLxcEnterNamespace(virDomainPtr domain,
* exec() has yet been performed.
*
* Returns 0 on success, -1 on error
+ *
+ * Since: v1.0.4
+ *
*/
int
virDomainLxcEnterSecurityLabel(virSecurityModelPtr model,
@@ -283,6 +292,9 @@ virDomainLxcEnterSecurityLabel(virSecurityModelPtr model,
* with the container @domain.
*
* Returns 0 on success, -1 on error
+ *
+ * Since: v2.0.0
+ *
*/
int virDomainLxcEnterCGroup(virDomainPtr domain,
unsigned int flags)
--
2.35.1
[PATCH v3 21/30] docstring: Fix and append Since to virDomainMemoryModFlags
This commit is similar to "docs: Fix generated documentation of
virConnectListAllNodeDeviceFlags", check it out for more info.
Signed-off-by: Victor Toso
---
include/libvirt/libvirt-domain.h | 13 ++---
1 file changed, 6 insertions(+), 7 deletions(-)
diff --git a/include/libvirt/libvirt-domain.h b/include/libvirt/libvirt-domain.h
index 27a680a907..67cbc0d08e 100644
--- a/include/libvirt/libvirt-domain.h
+++ b/include/libvirt/libvirt-domain.h
@@ -1958,18 +1958,17 @@ int virDomainGetMemoryParameters(virDomainPtr
domain,
* virDomainMemoryModFlags:
*
* Memory size modification flags.
+ * These flags may be bitwise-OR'd in.
*
- * Since: v1.0.0
+ * Since: v0.9.0
*
*/
typedef enum {
-/* See virDomainModificationImpact for these flags. (Since: v1.0.0) */
-VIR_DOMAIN_MEM_CURRENT = VIR_DOMAIN_AFFECT_CURRENT,
-VIR_DOMAIN_MEM_LIVE= VIR_DOMAIN_AFFECT_LIVE,
-VIR_DOMAIN_MEM_CONFIG = VIR_DOMAIN_AFFECT_CONFIG,
+VIR_DOMAIN_MEM_CURRENT = VIR_DOMAIN_AFFECT_CURRENT, /* See
virDomainModificationImpact (Since: v0.9.1) */
+VIR_DOMAIN_MEM_LIVE= VIR_DOMAIN_AFFECT_LIVE, /* See
virDomainModificationImpact (Since: v0.9.0) */
+VIR_DOMAIN_MEM_CONFIG = VIR_DOMAIN_AFFECT_CONFIG, /* See
virDomainModificationImpact (Since: v0.9.0) */
-/* Additionally, these flags may be bitwise-OR'd in. (Since: v1.0.0) */
-VIR_DOMAIN_MEM_MAXIMUM = (1 << 2), /* affect Max rather than current */
+VIR_DOMAIN_MEM_MAXIMUM = (1 << 2), /* affect Max rather than current
(Since: v0.9.1) */
} virDomainMemoryModFlags;
--
2.35.1
[PATCH v3 12/30] docstring: typedef: admin:: Add 'Since version' metadata
Either create or append to existing docstring, the version (git tag)
that a given typedef was introduced in the format:
Since: v1.2.3
Signed-off-by: Victor Toso
---
include/libvirt/libvirt-admin.h | 24
1 file changed, 24 insertions(+)
diff --git a/include/libvirt/libvirt-admin.h b/include/libvirt/libvirt-admin.h
index defca505f8..c73cf6e7da 100644
--- a/include/libvirt/libvirt-admin.h
+++ b/include/libvirt/libvirt-admin.h
@@ -37,6 +37,9 @@ extern "C" {
*
* a virAdmConnect is a private structure representing a connection to
* libvirt daemon.
+ *
+ * Since: v1.2.17
+ *
*/
typedef struct _virAdmConnect virAdmConnect;
@@ -45,6 +48,9 @@ typedef struct _virAdmConnect virAdmConnect;
*
* a virAdmServer is a private structure and client-side representation of
* a remote server object
+ *
+ * Since: v1.3.2
+ *
*/
typedef struct _virAdmServer virAdmServer;
@@ -53,6 +59,9 @@ typedef struct _virAdmServer virAdmServer;
*
* a virAdmClient is a private structure and client-side representation of
* a remote server's client object (as server sees clients connected to it)
+ *
+ * Since: v1.3.5
+ *
*/
typedef struct _virAdmClient virAdmClient;
@@ -62,6 +71,9 @@ typedef struct _virAdmClient virAdmClient;
* a virAdmConnectPtr is pointer to a virAdmConnect private structure,
* this is the type used to reference a connection to the daemon
* in the API.
+ *
+ * Since: v1.2.17
+ *
*/
typedef virAdmConnect *virAdmConnectPtr;
@@ -71,6 +83,9 @@ typedef virAdmConnect *virAdmConnectPtr;
* a virAdmServerPtr is a pointer to a virAdmServer structure,
* this is the type used to reference client-side representation of a
* remote server object throughout all the APIs.
+ *
+ * Since: v1.3.2
+ *
*/
typedef virAdmServer *virAdmServerPtr;
@@ -80,6 +95,9 @@ typedef virAdmServer *virAdmServerPtr;
* a virAdmClientPtr is a pointer to a virAdmClient structure,
* this is the type used to reference client-side representation of a
* client object throughout all the APIs.
+ *
+ * Since: v1.3.5
+ *
*/
typedef virAdmClient *virAdmClientPtr;
@@ -222,6 +240,12 @@ long long virAdmClientGetTimestamp(virAdmClientPtr client);
int virAdmClientGetTransport(virAdmClientPtr client);
int virAdmClientFree(virAdmClientPtr client);
+/**
+ * virClientTransport:
+ *
+ * Since: v1.3.5
+ *
+ */
typedef enum {
VIR_CLIENT_TRANS_UNIX = 0, /* connection via UNIX socket (Since: v1.3.5) */
VIR_CLIENT_TRANS_TCP, /* connection via unencrypted TCP socket
(Since: v1.3.5) */
--
2.35.1
[PATCH v3 17/30] docstring: libvirt-common: Add 'Since version' metadata
Similarly to previous commits but with the targeting libvirt-common
in a batch.
Either create or append to existing docstring, the version (git tag)
that a given typedef, enum value, macro or function was introduced
in the format:
Since: v1.2.3
Signed-off-by: Victor Toso
---
include/libvirt/libvirt-common.h.in | 54 ---
src/util/virtypedparam-public.c | 57 +
2 files changed, 98 insertions(+), 13 deletions(-)
diff --git a/include/libvirt/libvirt-common.h.in
b/include/libvirt/libvirt-common.h.in
index 4661ee9857..c2426809b6 100644
--- a/include/libvirt/libvirt-common.h.in
+++ b/include/libvirt/libvirt-common.h.in
@@ -70,6 +70,8 @@ extern "C" {
*
* Macro providing the version of the library as
* version * 1,000,000 + minor * 1000 + micro
+ *
+ * Since: v0.0.1
*/
# define LIBVIR_VERSION_NUMBER @LIBVIRT_VERSION_NUMBER@
@@ -86,6 +88,8 @@ extern "C" {
* #if LIBVIR_CHECK_VERSION(1,1,3)
* // some code that only works in 1.1.3 and newer
* #endif
+ *
+ * Since: v1.2.0
*/
# define LIBVIR_CHECK_VERSION(major, minor, micro) \
((major) * 100 + (minor) * 1000 + (micro) <= LIBVIR_VERSION_NUMBER)
@@ -104,17 +108,26 @@ extern "C" {
* from a context which is not re-entrant safe. Failure to
* abide by this requirement may lead to application deadlocks
* or crashes.
+ *
+ * Since: v0.5.0
+ *
*/
typedef void (*virFreeCallback)(void *opaque);
+/**
+ * virConnectCloseReason:
+ *
+ * Since: v0.10.0
+ *
+ */
typedef enum {
-VIR_CONNECT_CLOSE_REASON_ERROR = 0, /* Misc I/O error */
-VIR_CONNECT_CLOSE_REASON_EOF = 1, /* End-of-file from server */
-VIR_CONNECT_CLOSE_REASON_KEEPALIVE = 2, /* Keepalive timer triggered */
-VIR_CONNECT_CLOSE_REASON_CLIENT= 3, /* Client requested it */
+VIR_CONNECT_CLOSE_REASON_ERROR = 0, /* Misc I/O error (Since: v0.10.0)
*/
+VIR_CONNECT_CLOSE_REASON_EOF = 1, /* End-of-file from server (Since:
v0.10.0) */
+VIR_CONNECT_CLOSE_REASON_KEEPALIVE = 2, /* Keepalive timer triggered
(Since: v0.10.0) */
+VIR_CONNECT_CLOSE_REASON_CLIENT= 3, /* Client requested it (Since:
v0.10.0) */
# ifdef VIR_ENUM_SENTINELS
-VIR_CONNECT_CLOSE_REASON_LAST
+VIR_CONNECT_CLOSE_REASON_LAST /* (Since: v0.10.0) */
# endif
} virConnectCloseReason;
@@ -122,18 +135,20 @@ typedef enum {
* virTypedParameterType:
*
* Express the type of a virTypedParameter
+ *
+ * Since: v0.9.2
*/
typedef enum {
-VIR_TYPED_PARAM_INT = 1, /* integer case */
-VIR_TYPED_PARAM_UINT= 2, /* unsigned integer case */
-VIR_TYPED_PARAM_LLONG = 3, /* long long case */
-VIR_TYPED_PARAM_ULLONG = 4, /* unsigned long long case */
-VIR_TYPED_PARAM_DOUBLE = 5, /* double case */
-VIR_TYPED_PARAM_BOOLEAN = 6, /* boolean(character) case */
-VIR_TYPED_PARAM_STRING = 7, /* string case */
+VIR_TYPED_PARAM_INT = 1, /* integer case (Since: v0.9.2) */
+VIR_TYPED_PARAM_UINT= 2, /* unsigned integer case (Since: v0.9.2) */
+VIR_TYPED_PARAM_LLONG = 3, /* long long case (Since: v0.9.2) */
+VIR_TYPED_PARAM_ULLONG = 4, /* unsigned long long case (Since: v0.9.2) */
+VIR_TYPED_PARAM_DOUBLE = 5, /* double case (Since: v0.9.2) */
+VIR_TYPED_PARAM_BOOLEAN = 6, /* boolean(character) case (Since: v0.9.2) */
+VIR_TYPED_PARAM_STRING = 7, /* string case (Since: v0.9.8) */
# ifdef VIR_ENUM_SENTINELS
-VIR_TYPED_PARAM_LAST
+VIR_TYPED_PARAM_LAST /* (Since: v0.9.10) */
# endif
} virTypedParameterType;
@@ -143,6 +158,8 @@ typedef enum {
* Flags related to libvirt APIs that use virTypedParameter.
*
* These enums should not conflict with those of virDomainModificationImpact.
+ *
+ * Since: v0.9.8
*/
typedef enum {
/* 1 << 0 is reserved for virDomainModificationImpact */
@@ -157,6 +174,8 @@ typedef enum {
* the user does not have to worry about it; however, manually
* setting the flag can be used to reject servers that cannot
* return typed strings, even if no strings would be returned.
+ *
+ * Since: v0.9.8
*/
VIR_TYPED_PARAM_STRING_OKAY = 1 << 2,
@@ -166,6 +185,9 @@ typedef enum {
* VIR_TYPED_PARAM_FIELD_LENGTH:
*
* Macro providing the field length of virTypedParameter name
+ *
+ * Since: v0.9.2
+ *
*/
# define VIR_TYPED_PARAM_FIELD_LENGTH 80
@@ -177,6 +199,9 @@ typedef enum {
* The types virSchedParameter, virBlkioParameter, and
* virMemoryParameter are aliases of this type, for use when
* targeting libvirt earlier than 0.9.2.
+ *
+ * Since: v0.9.2
+ *
*/
typedef struct _virTypedParameter virTypedParameter;
@@ -198,6 +223,9 @@ struct _virTypedParameter {
* virTypedParameterPtr:
*
* a pointer to a virTypedParameter structure.
+ *
+ * Since: v0.9.2
+ *
*/
typedef virTypedParameter *virTypedParameterPtr;
diff --git a/src/util/virtypedparam-public.c b/src/util/virtypedparam-public.c
index 4cb54f7ab1..2e213f2ace 100644
---
[PATCH v3 19/30] docstring: Fix and append Since to virConnectListAllStoragePoolsFlags
This commit is similar to "docs: Fix generated documentation of
virConnectListAllNodeDeviceFlags", check it out for more info.
Signed-off-by: Victor Toso
---
include/libvirt/libvirt-storage.h | 49 +++
1 file changed, 24 insertions(+), 25 deletions(-)
diff --git a/include/libvirt/libvirt-storage.h
b/include/libvirt/libvirt-storage.h
index 8b57b1f2e8..e4980ae95f 100644
--- a/include/libvirt/libvirt-storage.h
+++ b/include/libvirt/libvirt-storage.h
@@ -317,34 +317,33 @@ int
virConnectListDefinedStoragePools(virConnectPtr conn,
* Note that these flags come in groups; if all bits from a group are 0,
* then that group is not used to filter results.
*
- * Since: v1.0.0
+ * Since: v0.10.2
*
*/
typedef enum {
-VIR_CONNECT_LIST_STORAGE_POOLS_INACTIVE = 1 << 0,
-VIR_CONNECT_LIST_STORAGE_POOLS_ACTIVE= 1 << 1,
-
-VIR_CONNECT_LIST_STORAGE_POOLS_PERSISTENT= 1 << 2,
-VIR_CONNECT_LIST_STORAGE_POOLS_TRANSIENT = 1 << 3,
-
-VIR_CONNECT_LIST_STORAGE_POOLS_AUTOSTART = 1 << 4,
-VIR_CONNECT_LIST_STORAGE_POOLS_NO_AUTOSTART = 1 << 5,
-
-/* List pools by type */
-VIR_CONNECT_LIST_STORAGE_POOLS_DIR = 1 << 6,
-VIR_CONNECT_LIST_STORAGE_POOLS_FS= 1 << 7,
-VIR_CONNECT_LIST_STORAGE_POOLS_NETFS = 1 << 8,
-VIR_CONNECT_LIST_STORAGE_POOLS_LOGICAL = 1 << 9,
-VIR_CONNECT_LIST_STORAGE_POOLS_DISK = 1 << 10,
-VIR_CONNECT_LIST_STORAGE_POOLS_ISCSI = 1 << 11,
-VIR_CONNECT_LIST_STORAGE_POOLS_SCSI = 1 << 12,
-VIR_CONNECT_LIST_STORAGE_POOLS_MPATH = 1 << 13,
-VIR_CONNECT_LIST_STORAGE_POOLS_RBD = 1 << 14,
-VIR_CONNECT_LIST_STORAGE_POOLS_SHEEPDOG = 1 << 15,
-VIR_CONNECT_LIST_STORAGE_POOLS_GLUSTER = 1 << 16,
-VIR_CONNECT_LIST_STORAGE_POOLS_ZFS = 1 << 17,
-VIR_CONNECT_LIST_STORAGE_POOLS_VSTORAGE = 1 << 18,
-VIR_CONNECT_LIST_STORAGE_POOLS_ISCSI_DIRECT = 1 << 19,
+VIR_CONNECT_LIST_STORAGE_POOLS_INACTIVE = 1 << 0, /* (Since: v0.10.2)
*/
+VIR_CONNECT_LIST_STORAGE_POOLS_ACTIVE= 1 << 1, /* (Since: v0.10.2)
*/
+
+VIR_CONNECT_LIST_STORAGE_POOLS_PERSISTENT= 1 << 2, /* (Since: v0.10.2)
*/
+VIR_CONNECT_LIST_STORAGE_POOLS_TRANSIENT = 1 << 3, /* (Since: v0.10.2)
*/
+
+VIR_CONNECT_LIST_STORAGE_POOLS_AUTOSTART = 1 << 4, /* (Since: v0.10.2)
*/
+VIR_CONNECT_LIST_STORAGE_POOLS_NO_AUTOSTART = 1 << 5, /* (Since: v0.10.2)
*/
+
+VIR_CONNECT_LIST_STORAGE_POOLS_DIR = 1 << 6, /* (Since: v0.10.2)
*/
+VIR_CONNECT_LIST_STORAGE_POOLS_FS= 1 << 7, /* (Since: v0.10.2)
*/
+VIR_CONNECT_LIST_STORAGE_POOLS_NETFS = 1 << 8, /* (Since: v0.10.2)
*/
+VIR_CONNECT_LIST_STORAGE_POOLS_LOGICAL = 1 << 9, /* (Since: v0.10.2)
*/
+VIR_CONNECT_LIST_STORAGE_POOLS_DISK = 1 << 10, /* (Since:
v0.10.2) */
+VIR_CONNECT_LIST_STORAGE_POOLS_ISCSI = 1 << 11, /* (Since:
v0.10.2) */
+VIR_CONNECT_LIST_STORAGE_POOLS_SCSI = 1 << 12, /* (Since:
v0.10.2) */
+VIR_CONNECT_LIST_STORAGE_POOLS_MPATH = 1 << 13, /* (Since:
v0.10.2) */
+VIR_CONNECT_LIST_STORAGE_POOLS_RBD = 1 << 14, /* (Since:
v0.10.2) */
+VIR_CONNECT_LIST_STORAGE_POOLS_SHEEPDOG = 1 << 15, /* (Since:
v0.10.2) */
+VIR_CONNECT_LIST_STORAGE_POOLS_GLUSTER = 1 << 16, /* (Since: v1.2.1)
*/
+VIR_CONNECT_LIST_STORAGE_POOLS_ZFS = 1 << 17, /* (Since: v1.2.8)
*/
+VIR_CONNECT_LIST_STORAGE_POOLS_VSTORAGE = 1 << 18, /* (Since: v3.1.0)
*/
+VIR_CONNECT_LIST_STORAGE_POOLS_ISCSI_DIRECT = 1 << 19, /* (Since: v5.6.0)
*/
} virConnectListAllStoragePoolsFlags;
int virConnectListAllStoragePools(virConnectPtr conn,
--
2.35.1
[PATCH v3 18/30] docstring: Fix generated documentation of virStorageVolInfoFlags
This commit is similar to "docs: Fix generated documentation of
virConnectListAllNodeDeviceFlags", check it out for more info.
Using git diff --word-diff to show the fixed output xml (redacted).
-]
{+type='virStorageVolInfoFlags' version='3.0.0' info='Return the physical
size in allocation'/>+}
...
-]
{+version='3.0.0'/>+}
Signed-off-by: Victor Toso
---
include/libvirt/libvirt-storage.h | 7 ++-
1 file changed, 2 insertions(+), 5 deletions(-)
diff --git a/include/libvirt/libvirt-storage.h
b/include/libvirt/libvirt-storage.h
index 434454f455..8b57b1f2e8 100644
--- a/include/libvirt/libvirt-storage.h
+++ b/include/libvirt/libvirt-storage.h
@@ -248,11 +248,8 @@ typedef enum {
*
*/
typedef enum {
-VIR_STORAGE_VOL_USE_ALLOCATION = 0,
-
-/* Return the physical size in allocation */
-VIR_STORAGE_VOL_GET_PHYSICAL = 1 << 0,
-
+VIR_STORAGE_VOL_USE_ALLOCATION = 0, /* (Since: v3.0.0) */
+VIR_STORAGE_VOL_GET_PHYSICAL = 1 << 0, /* Return the physical size in
allocation (Since: v3.0.0) */
} virStorageVolInfoFlags;
/**
--
2.35.1
[PATCH v3 11/30] docstring: typedef: qemu:: Add 'Since version' metadata
Either create or append to existing docstring, the version (git tag)
that a given typedef was introduced in the format:
Since: v1.2.3
Signed-off-by: Victor Toso
---
include/libvirt/libvirt-qemu.h | 18 ++
1 file changed, 18 insertions(+)
diff --git a/include/libvirt/libvirt-qemu.h b/include/libvirt/libvirt-qemu.h
index a2569a9fbd..9697b54158 100644
--- a/include/libvirt/libvirt-qemu.h
+++ b/include/libvirt/libvirt-qemu.h
@@ -30,6 +30,12 @@
extern "C" {
# endif
+/**
+ * virDomainQemuMonitorCommandFlags:
+ *
+ * Since: v0.8.8
+ *
+ */
typedef enum {
VIR_DOMAIN_QEMU_MONITOR_COMMAND_DEFAULT = 0, /* (Since: v0.8.8) */
VIR_DOMAIN_QEMU_MONITOR_COMMAND_HMP = (1 << 0), /* cmd is in HMP
(Since: v0.8.8) */
@@ -50,6 +56,12 @@ virDomainPtr virDomainQemuAttach(virConnectPtr domain,
unsigned int pid_value,
unsigned int flags);
+/**
+ * virDomainQemuAgentCommandTimeoutValues:
+ *
+ * Since: v0.10.0
+ *
+ */
typedef enum {
VIR_DOMAIN_QEMU_AGENT_COMMAND_MIN =
VIR_DOMAIN_AGENT_RESPONSE_TIMEOUT_BLOCK, /* (Since: v0.10.0) */
VIR_DOMAIN_QEMU_AGENT_COMMAND_BLOCK =
VIR_DOMAIN_AGENT_RESPONSE_TIMEOUT_BLOCK, /* (Since: v0.10.0) */
@@ -84,6 +96,12 @@ typedef void
(*virConnectDomainQemuMonitorEventCallback)(virConnectPtr conn,
void *opaque);
+/**
+ * virConnectDomainQemuMonitorEventRegisterFlags:
+ *
+ * Since: v1.2.3
+ *
+ */
typedef enum {
/* Event filter is a regex rather than a literal string (Since: v1.2.3) */
VIR_CONNECT_DOMAIN_QEMU_MONITOR_EVENT_REGISTER_REGEX = (1 << 0),
--
2.35.1
[PATCH v3 14/30] docstring: function: qemu: Add 'Since version' metadata
Either create or append to existing docstring, the version (git tag)
that a given function was introduced in the format:
Since: v1.2.3
Signed-off-by: Victor Toso
---
include/libvirt/libvirt-qemu.h | 3 +++
src/libvirt-qemu.c | 18 ++
2 files changed, 21 insertions(+)
diff --git a/include/libvirt/libvirt-qemu.h b/include/libvirt/libvirt-qemu.h
index 9697b54158..fb422a3a21 100644
--- a/include/libvirt/libvirt-qemu.h
+++ b/include/libvirt/libvirt-qemu.h
@@ -86,6 +86,9 @@ char *virDomainQemuAgentCommand(virDomainPtr domain, const
char *cmd,
*
* The callback signature to use when registering for a qemu monitor
* event with virConnectDomainQemuMonitorEventRegister().
+ *
+ * Since: v1.2.3
+ *
*/
typedef void (*virConnectDomainQemuMonitorEventCallback)(virConnectPtr conn,
virDomainPtr dom,
diff --git a/src/libvirt-qemu.c b/src/libvirt-qemu.c
index 896aba2f0b..b80cd2b7ff 100644
--- a/src/libvirt-qemu.c
+++ b/src/libvirt-qemu.c
@@ -61,6 +61,9 @@ VIR_LOG_INIT("libvirt-qemu");
*
* Returns 0 in case of success, -1 in case of failure
*
+ * Since: v0.8.3
+ *
+ *
*/
int
virDomainQemuMonitorCommand(virDomainPtr domain, const char *cmd,
@@ -131,6 +134,9 @@ virDomainQemuMonitorCommand(virDomainPtr domain, const char
*cmd,
* @cmd, and the caller must free this string.
*
* Returns 0 in case of success, -1 in case of failure
+ *
+ * Since: v8.2.0
+ *
*/
int
virDomainQemuMonitorCommandWithFiles(virDomainPtr domain,
@@ -216,6 +222,9 @@ virDomainQemuMonitorCommandWithFiles(virDomainPtr domain,
* normally (provided the above requirements were honored).
*
* Returns a new domain object on success, NULL otherwise
+ *
+ * Since: v0.9.4
+ *
*/
virDomainPtr
virDomainQemuAttach(virConnectPtr conn,
@@ -272,6 +281,9 @@ virDomainQemuAttach(virConnectPtr conn,
* positive value: wait for @timeout seconds
*
* Returns strings if success, NULL in failure.
+ *
+ * Since: v0.10.0
+ *
*/
char *
virDomainQemuAgentCommand(virDomainPtr domain,
@@ -350,6 +362,9 @@ virDomainQemuAgentCommand(virDomainPtr domain,
* be passed to the virConnectDomainQemuMonitorEventDeregister() method.
*
* Returns a callback identifier on success, -1 on failure
+ *
+ * Since: v1.2.3
+ *
*/
int
virConnectDomainQemuMonitorEventRegister(virConnectPtr conn,
@@ -404,6 +419,9 @@ virConnectDomainQemuMonitorEventRegister(virConnectPtr conn,
* method.
*
* Returns 0 on success, -1 on failure
+ *
+ * Since: v1.2.3
+ *
*/
int
virConnectDomainQemuMonitorEventDeregister(virConnectPtr conn,
--
2.35.1
[PATCH v3 09/30] docstring: macros: admin: Add 'Since version' metadata
Either create or append to existing docstring, the version (git tag) that a given macro was introduced in the format: Since: v1.2.3 Signed-off-by: Victor Toso --- include/libvirt/libvirt-admin.h | 60 + 1 file changed, 60 insertions(+) diff --git a/include/libvirt/libvirt-admin.h b/include/libvirt/libvirt-admin.h index f65886f20d..defca505f8 100644 --- a/include/libvirt/libvirt-admin.h +++ b/include/libvirt/libvirt-admin.h @@ -132,6 +132,9 @@ virAdmServerPtr virAdmConnectLookupServer(virAdmConnectPtr conn, * VIR_THREADPOOL_WORKERS_MIN: * Macro for the threadpool minWorkers limit: represents the bottom limit to * number of active workers in threadpool, as VIR_TYPED_PARAM_UINT. + * + * Since: v1.3.4 + * */ # define VIR_THREADPOOL_WORKERS_MIN "minWorkers" @@ -142,6 +145,9 @@ virAdmServerPtr virAdmConnectLookupServer(virAdmConnectPtr conn, * number of active workers in threadpool, as VIR_TYPED_PARAM_UINT. * The value of this limit has to be greater than VIR_THREADPOOL_WORKERS_MIN * at all times. + * + * Since: v1.3.4 + * */ # define VIR_THREADPOOL_WORKERS_MAX "maxWorkers" @@ -150,6 +156,9 @@ virAdmServerPtr virAdmConnectLookupServer(virAdmConnectPtr conn, * VIR_THREADPOOL_WORKERS_PRIORITY: * Macro for the threadpool nPrioWorkers attribute: represents the current number * of active priority workers in threadpool, as VIR_TYPED_PARAM_UINT. + * + * Since: v1.3.4 + * */ # define VIR_THREADPOOL_WORKERS_PRIORITY "prioWorkers" @@ -161,6 +170,9 @@ virAdmServerPtr virAdmConnectLookupServer(virAdmConnectPtr conn, * * NOTE: This attribute is read-only and any attempt to set it will be denied * by daemon + * + * Since: v1.3.4 + * */ # define VIR_THREADPOOL_WORKERS_FREE "freeWorkers" @@ -172,6 +184,9 @@ virAdmServerPtr virAdmConnectLookupServer(virAdmConnectPtr conn, * * NOTE: This attribute is read-only and any attempt to set it will be denied * by daemon + * + * Since: v1.3.4 + * */ # define VIR_THREADPOOL_WORKERS_CURRENT "nWorkers" @@ -183,6 +198,9 @@ virAdmServerPtr virAdmConnectLookupServer(virAdmConnectPtr conn, * * NOTE: This attribute is read-only and any attempt to set it will be denied * by daemon + * + * Since: v1.3.4 + * */ # define VIR_THREADPOOL_JOB_QUEUE_DEPTH "jobQueueDepth" @@ -233,6 +251,9 @@ virAdmServerLookupClient(virAdmServerPtr srv, * * NOTE: This attribute is read-only and any attempt to set it will be denied * by daemon + * + * Since: v1.3.5 + * */ # define VIR_CLIENT_INFO_READONLY "readonly" @@ -244,6 +265,9 @@ virAdmServerLookupClient(virAdmServerPtr srv, * * NOTE: This attribute is read-only and any attempt to set it will be denied * by daemon + * + * Since: v1.3.5 + * */ # define VIR_CLIENT_INFO_SOCKET_ADDR "sock_addr" @@ -255,6 +279,9 @@ virAdmServerLookupClient(virAdmServerPtr srv, * * NOTE: This attribute is read-only and any attempt to set it will be denied * by daemon + * + * Since: v1.3.5 + * */ # define VIR_CLIENT_INFO_SASL_USER_NAME "sasl_user_name" @@ -267,6 +294,9 @@ virAdmServerLookupClient(virAdmServerPtr srv, * * NOTE: This attribute is read-only and any attempt to set it will be denied * by daemon + * + * Since: v1.3.5 + * */ # define VIR_CLIENT_INFO_X509_DISTINGUISHED_NAME "tls_x509_dname" @@ -279,6 +309,9 @@ virAdmServerLookupClient(virAdmServerPtr srv, * * NOTE: This attribute is read-only and any attempt to set it will be denied * by daemon + * + * Since: v1.3.5 + * */ # define VIR_CLIENT_INFO_UNIX_USER_ID "unix_user_id" @@ -291,6 +324,9 @@ virAdmServerLookupClient(virAdmServerPtr srv, * * NOTE: This attribute is read-only and any attempt to set it will be denied * by daemon + * + * Since: v1.3.5 + * */ # define VIR_CLIENT_INFO_UNIX_USER_NAME "unix_user_name" @@ -303,6 +339,9 @@ virAdmServerLookupClient(virAdmServerPtr srv, * * NOTE: This attribute is read-only and any attempt to set it will be denied * by daemon + * + * Since: v1.3.5 + * */ # define VIR_CLIENT_INFO_UNIX_GROUP_ID "unix_group_id" @@ -315,6 +354,9 @@ virAdmServerLookupClient(virAdmServerPtr srv, * * NOTE: This attribute is read-only and any attempt to set it will be denied * by daemon + * + * Since: v1.3.5 + * */ # define VIR_CLIENT_INFO_UNIX_GROUP_NAME "unix_group_name" @@ -327,6 +369,9 @@ virAdmServerLookupClient(virAdmServerPtr srv, * * NOTE: This attribute is read-only and any attempt to set it will be denied * by daemon + * + * Since: v1.3.5 + * */ # define VIR_CLIENT_INFO_UNIX_PROCESS_ID "unix_process_id" @@ -339,6 +384,9 @@ virAdmServerLookupClient(virAdmServerPtr srv, * * NOTE: This attribute is read-only and any attempt to set it will be denied * by daemon + * + * Since: v1.3.5 + * */ # define VIR_CLIENT_INFO_SELINUX_CONTEXT "selinux_context" @@ -356,6 +404,9 @@ int virAdmClientClose(virAdmClientPtr client, unsigned int flags); * VIR_SERVER_CLIENTS_MAX: * Macro for per-server
[PATCH v3 07/30] docstring: enums: admin: Add 'Since version' metadata
Either create or append to existing docstring, the version (git tag)
that a given enum value was introduced in the format:
Since: v1.2.3
Signed-off-by: Victor Toso
---
include/libvirt/libvirt-admin.h | 8
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/include/libvirt/libvirt-admin.h b/include/libvirt/libvirt-admin.h
index e414f776e4..f65886f20d 100644
--- a/include/libvirt/libvirt-admin.h
+++ b/include/libvirt/libvirt-admin.h
@@ -205,12 +205,12 @@ int virAdmClientGetTransport(virAdmClientPtr client);
int virAdmClientFree(virAdmClientPtr client);
typedef enum {
-VIR_CLIENT_TRANS_UNIX = 0, /* connection via UNIX socket */
-VIR_CLIENT_TRANS_TCP, /* connection via unencrypted TCP socket */
-VIR_CLIENT_TRANS_TLS, /* connection via encrypted TCP socket */
+VIR_CLIENT_TRANS_UNIX = 0, /* connection via UNIX socket (Since: v1.3.5) */
+VIR_CLIENT_TRANS_TCP, /* connection via unencrypted TCP socket
(Since: v1.3.5) */
+VIR_CLIENT_TRANS_TLS, /* connection via encrypted TCP socket (Since:
v1.3.5) */
# ifdef VIR_ENUM_SENTINELS
-VIR_CLIENT_TRANS_LAST
+VIR_CLIENT_TRANS_LAST /* (Since: v1.3.5) */
# endif
} virClientTransport;
--
2.35.1
[PATCH v3 08/30] docstring: macros: libvirt: Add 'Since version' metadata
Either create or append to existing docstring, the version (git tag)
that a given macro was introduced in the format:
Since: v1.2.3
Signed-off-by: Victor Toso
---
include/libvirt/libvirt-domain.h | 663 +-
include/libvirt/libvirt-host.h| 123 ++
include/libvirt/libvirt-network.h | 24 ++
include/libvirt/libvirt-nodedev.h | 3 +
include/libvirt/libvirt-secret.h | 3 +
include/libvirt/libvirt-storage.h | 3 +
6 files changed, 810 insertions(+), 9 deletions(-)
diff --git a/include/libvirt/libvirt-domain.h b/include/libvirt/libvirt-domain.h
index de2d14d4af..01ea2a750f 100644
--- a/include/libvirt/libvirt-domain.h
+++ b/include/libvirt/libvirt-domain.h
@@ -315,6 +315,9 @@ typedef enum {
*
* Macro represents proportional weight of the scheduler used on the
* host cpu, when using the posix scheduler, as a ullong.
+ *
+ * Since: v0.9.7
+ *
*/
# define VIR_DOMAIN_SCHEDULER_CPU_SHARES "cpu_shares"
@@ -323,6 +326,9 @@ typedef enum {
*
* Macro represents the enforcement period for a quota, in microseconds,
* for whole domain, when using the posix scheduler, as a ullong.
+ *
+ * Since: v1.3.3
+ *
*/
# define VIR_DOMAIN_SCHEDULER_GLOBAL_PERIOD "global_period"
@@ -331,6 +337,9 @@ typedef enum {
*
* Macro represents the maximum bandwidth to be used within a period for
* whole domain, when using the posix scheduler, as an llong.
+ *
+ * Since: v1.3.3
+ *
*/
# define VIR_DOMAIN_SCHEDULER_GLOBAL_QUOTA "global_quota"
@@ -339,6 +348,9 @@ typedef enum {
*
* Macro represents the enforcement period for a quota, in microseconds,
* for vcpus only, when using the posix scheduler, as a ullong.
+ *
+ * Since: v0.9.7
+ *
*/
# define VIR_DOMAIN_SCHEDULER_VCPU_PERIOD "vcpu_period"
@@ -347,6 +359,9 @@ typedef enum {
*
* Macro represents the maximum bandwidth to be used within a period for
* vcpus only, when using the posix scheduler, as an llong.
+ *
+ * Since: v0.9.7
+ *
*/
# define VIR_DOMAIN_SCHEDULER_VCPU_QUOTA "vcpu_quota"
@@ -356,6 +371,9 @@ typedef enum {
* Macro represents the enforcement period for a quota in microseconds,
* when using the posix scheduler, for all emulator activity not tied to
* vcpus, as a ullong.
+ *
+ * Since: v0.10.0
+ *
*/
# define VIR_DOMAIN_SCHEDULER_EMULATOR_PERIOD "emulator_period"
@@ -365,6 +383,9 @@ typedef enum {
* Macro represents the maximum bandwidth to be used within a period for
* all emulator activity not tied to vcpus, when using the posix scheduler,
* as an llong.
+ *
+ * Since: v0.10.0
+ *
*/
# define VIR_DOMAIN_SCHEDULER_EMULATOR_QUOTA "emulator_quota"
@@ -373,6 +394,9 @@ typedef enum {
*
* Macro represents the enforcement period for a quota, in microseconds,
* for IOThreads only, when using the posix scheduler, as a ullong.
+ *
+ * Since: v2.2.0
+ *
*/
# define VIR_DOMAIN_SCHEDULER_IOTHREAD_PERIOD "iothread_period"
@@ -381,6 +405,9 @@ typedef enum {
*
* Macro represents the maximum bandwidth to be used within a period for
* IOThreads only, when using the posix scheduler, as an llong.
+ *
+ * Since: v2.2.0
+ *
*/
# define VIR_DOMAIN_SCHEDULER_IOTHREAD_QUOTA "iothread_quota"
@@ -389,6 +416,9 @@ typedef enum {
*
* Macro represents the relative weight, when using the credit
* scheduler, as a uint.
+ *
+ * Since: v0.9.7
+ *
*/
# define VIR_DOMAIN_SCHEDULER_WEIGHT "weight"
@@ -397,6 +427,9 @@ typedef enum {
*
* Macro represents the maximum scheduler cap, when using the credit
* scheduler, as a uint.
+ *
+ * Since: v0.9.7
+ *
*/
# define VIR_DOMAIN_SCHEDULER_CAP "cap"
@@ -405,6 +438,9 @@ typedef enum {
*
* Macro represents the scheduler reservation value, when using the
* allocation scheduler, as an llong.
+ *
+ * Since: v0.9.7
+ *
*/
# define VIR_DOMAIN_SCHEDULER_RESERVATION "reservation"
@@ -413,6 +449,9 @@ typedef enum {
*
* Macro represents the scheduler limit value, when using the
* allocation scheduler, as an llong.
+ *
+ * Since: v0.9.7
+ *
*/
# define VIR_DOMAIN_SCHEDULER_LIMIT "limit"
@@ -421,6 +460,9 @@ typedef enum {
*
* Macro represents the scheduler shares value, when using the
* allocation scheduler, as an int.
+ *
+ * Since: v0.9.7
+ *
*/
# define VIR_DOMAIN_SCHEDULER_SHARES "shares"
@@ -479,6 +521,9 @@ typedef virDomainBlockStatsStruct *virDomainBlockStatsPtr;
*
* Macro providing the field length of parameter names when using
* virDomainBlockStatsFlags().
+ *
+ * Since: v0.9.5
+ *
*/
# define VIR_DOMAIN_BLOCK_STATS_FIELD_LENGTH VIR_TYPED_PARAM_FIELD_LENGTH
@@ -487,6 +532,9 @@ typedef virDomainBlockStatsStruct *virDomainBlockStatsPtr;
*
* Macro represents the total number of read bytes of the
* block device, as an llong.
+ *
+ * Since: v0.9.5
+ *
*/
# define VIR_DOMAIN_BLOCK_STATS_READ_BYTES "rd_bytes"
@@ -495,6 +543,9 @@ typedef virDomainBlockStatsStruct *virDomainBlockStatsPtr;
*
* Macro represents the total read requests of the
* block device,
[PATCH v3 06/30] docstring: enums: qemu: Add 'Since version' metadata
Either create or append to existing docstring, the version (git tag)
that a given enum value was introduced in the format:
Since: v1.2.3
Signed-off-by: Victor Toso
---
include/libvirt/libvirt-qemu.h | 18 +-
1 file changed, 9 insertions(+), 9 deletions(-)
diff --git a/include/libvirt/libvirt-qemu.h b/include/libvirt/libvirt-qemu.h
index 98f2ac3823..a2569a9fbd 100644
--- a/include/libvirt/libvirt-qemu.h
+++ b/include/libvirt/libvirt-qemu.h
@@ -31,8 +31,8 @@ extern "C" {
# endif
typedef enum {
-VIR_DOMAIN_QEMU_MONITOR_COMMAND_DEFAULT = 0,
-VIR_DOMAIN_QEMU_MONITOR_COMMAND_HMP = (1 << 0), /* cmd is in HMP */
+VIR_DOMAIN_QEMU_MONITOR_COMMAND_DEFAULT = 0, /* (Since: v0.8.8) */
+VIR_DOMAIN_QEMU_MONITOR_COMMAND_HMP = (1 << 0), /* cmd is in HMP
(Since: v0.8.8) */
} virDomainQemuMonitorCommandFlags;
int virDomainQemuMonitorCommand(virDomainPtr domain, const char *cmd,
@@ -51,11 +51,11 @@ virDomainPtr virDomainQemuAttach(virConnectPtr domain,
unsigned int flags);
typedef enum {
-VIR_DOMAIN_QEMU_AGENT_COMMAND_MIN =
VIR_DOMAIN_AGENT_RESPONSE_TIMEOUT_BLOCK,
-VIR_DOMAIN_QEMU_AGENT_COMMAND_BLOCK =
VIR_DOMAIN_AGENT_RESPONSE_TIMEOUT_BLOCK,
-VIR_DOMAIN_QEMU_AGENT_COMMAND_DEFAULT =
VIR_DOMAIN_AGENT_RESPONSE_TIMEOUT_DEFAULT,
-VIR_DOMAIN_QEMU_AGENT_COMMAND_NOWAIT =
VIR_DOMAIN_AGENT_RESPONSE_TIMEOUT_NOWAIT,
-VIR_DOMAIN_QEMU_AGENT_COMMAND_SHUTDOWN = 60,
+VIR_DOMAIN_QEMU_AGENT_COMMAND_MIN =
VIR_DOMAIN_AGENT_RESPONSE_TIMEOUT_BLOCK, /* (Since: v0.10.0) */
+VIR_DOMAIN_QEMU_AGENT_COMMAND_BLOCK =
VIR_DOMAIN_AGENT_RESPONSE_TIMEOUT_BLOCK, /* (Since: v0.10.0) */
+VIR_DOMAIN_QEMU_AGENT_COMMAND_DEFAULT =
VIR_DOMAIN_AGENT_RESPONSE_TIMEOUT_DEFAULT, /* (Since: v0.10.0) */
+VIR_DOMAIN_QEMU_AGENT_COMMAND_NOWAIT =
VIR_DOMAIN_AGENT_RESPONSE_TIMEOUT_NOWAIT, /* (Since: v0.10.0) */
+VIR_DOMAIN_QEMU_AGENT_COMMAND_SHUTDOWN = 60, /* (Since: v1.2.15) */
} virDomainQemuAgentCommandTimeoutValues;
char *virDomainQemuAgentCommand(virDomainPtr domain, const char *cmd,
@@ -85,10 +85,10 @@ typedef void
(*virConnectDomainQemuMonitorEventCallback)(virConnectPtr conn,
typedef enum {
-/* Event filter is a regex rather than a literal string */
+/* Event filter is a regex rather than a literal string (Since: v1.2.3) */
VIR_CONNECT_DOMAIN_QEMU_MONITOR_EVENT_REGISTER_REGEX = (1 << 0),
-/* Event filter is case insensitive */
+/* Event filter is case insensitive (Since: v1.2.3) */
VIR_CONNECT_DOMAIN_QEMU_MONITOR_EVENT_REGISTER_NOCASE = (1 << 1),
} virConnectDomainQemuMonitorEventRegisterFlags;
--
2.35.1
[PATCH v3 04/30] docstring: variable: Move docstring from source to header file
virConnectAuthPtrDefault is the only variable that we export and
with the documentation being at the C file, it makes harder to find
it.
With this patch, the documentation of this variable can be found by
those who look at the header file for guidance plus, it will also be
included in the XML API, as the followup patch will fix apibuild.py
to store what is documented in the header file for this variable.
Note that the apibuild, does not do the same with .c files. It'd
require adding it for (parsing) recursion, similar to what is done
for functions. Considering the pros/cons, seems more reasonable to
move the docstring to the header file instead.
Signed-off-by: Victor Toso
---
include/libvirt/libvirt-host.h | 13 +
src/libvirt.c | 11 +--
2 files changed, 14 insertions(+), 10 deletions(-)
diff --git a/include/libvirt/libvirt-host.h b/include/libvirt/libvirt-host.h
index 1dc4b8a147..8cccf2921f 100644
--- a/include/libvirt/libvirt-host.h
+++ b/include/libvirt/libvirt-host.h
@@ -562,6 +562,19 @@ struct _virConnectAuth {
typedef struct _virConnectAuth virConnectAuth;
typedef virConnectAuth *virConnectAuthPtr;
+/*
+ * virConnectAuthPtrDefault:
+ *
+ * A default implementation of the authentication callbacks. This
+ * implementation is suitable for command line based tools. It will
+ * prompt for username, passwords, realm and one time keys as needed.
+ * It will print on STDOUT, and read from STDIN. If this is not
+ * suitable for the application's needs an alternative implementation
+ * should be provided.
+ *
+ * Since: v0.4.1
+ *
+ */
VIR_EXPORT_VAR virConnectAuthPtr virConnectAuthPtrDefault;
/**
diff --git a/src/libvirt.c b/src/libvirt.c
index 45315f484c..6cda75d1ca 100644
--- a/src/libvirt.c
+++ b/src/libvirt.c
@@ -197,16 +197,7 @@ static virConnectAuth virConnectAuthDefault = {
NULL,
};
-/*
- * virConnectAuthPtrDefault
- *
- * A default implementation of the authentication callbacks. This
- * implementation is suitable for command line based tools. It will
- * prompt for username, passwords, realm and one time keys as needed.
- * It will print on STDOUT, and read from STDIN. If this is not
- * suitable for the application's needs an alternative implementation
- * should be provided.
- */
+/* Explanation in the header file */
virConnectAuthPtr virConnectAuthPtrDefault =
static bool virGlobalError;
--
2.35.1
[PATCH v3 03/30] docstring: Fix generated documentation of virConnectListAllNodeDeviceFlags
scripts/apibuild.py does not handle well enum's with comments
between values. The outcome depends on whether the enum value has
its own docstring or not and if there is spaces between the enum
values or not.
Either way, virConnectListAllNodeDeviceFlags documentation is
explicit that this enum is about filtering node devices. We can move
the information that it is either by "capability" or "active" state
to the block of comment above.
Using git diff --word-diff to show the fixed ouput xml (redacted).
-]{+Matrix'/>+}
-]{+Queue'/>+}
-]{+info='DRM device'/>+}
-]{+info='FC Host Bus Adapter'/>+}
-]{+info='Mediated device'/>+}
-]{+info='Capable of mediated devices'/>+}
-]{+info='Network device'/>+}
-]{+info='PCI device'/>+}
-]{+device'/>+}
-]{+scsi_generic'/>+}
-]{+info='SCSI Host Bus Adapter'/>+}
-]{+Target'/>+}
-]{+info='System capability'/>+}
-]{+interface'/>+}
-]{+info='Device with VPD'/>+}
-]{+info='Capable of vport'/>+}
-]{+info='Inactive devices'/>+}
Signed-off-by: Victor Toso
---
include/libvirt/libvirt-nodedev.h | 5 ++---
1 file changed, 2 insertions(+), 3 deletions(-)
diff --git a/include/libvirt/libvirt-nodedev.h
b/include/libvirt/libvirt-nodedev.h
index 0c01d51aab..8efcd7f506 100644
--- a/include/libvirt/libvirt-nodedev.h
+++ b/include/libvirt/libvirt-nodedev.h
@@ -60,9 +60,9 @@ int virNodeListDevices
(virConnectPtr conn,
/*
* virConnectListAllNodeDevices:
*
- * Flags used to filter the returned node devices. */
+ * Flags used to filter either by capability or active state, the
+ * returned node devices. */
typedef enum {
-/* filter the devices by cap type */
VIR_CONNECT_LIST_NODE_DEVICES_CAP_SYSTEM= 1 << 0, /* System
capability */
VIR_CONNECT_LIST_NODE_DEVICES_CAP_PCI_DEV = 1 << 1, /* PCI device */
VIR_CONNECT_LIST_NODE_DEVICES_CAP_USB_DEV = 1 << 2, /* USB device */
@@ -86,7 +86,6 @@ typedef enum {
VIR_CONNECT_LIST_NODE_DEVICES_CAP_AP_MATRIX = 1 << 20, /* s390 AP
Matrix */
VIR_CONNECT_LIST_NODE_DEVICES_CAP_VPD = 1 << 21, /* Device with
VPD */
-/* filter the devices by active state */
VIR_CONNECT_LIST_NODE_DEVICES_INACTIVE = 1 << 30, /* Inactive
devices */
VIR_CONNECT_LIST_NODE_DEVICES_ACTIVE= 1U << 31, /* Active
devices */
} virConnectListAllNodeDeviceFlags;
--
2.35.1
[PATCH v3 01/30] syntax-check: sc_prohibit_nonreentrant: skip comments
It doesn't need to fail the test if a reentrant function is found in
a comment.
Fixes:
| ...
| prohibit_nonreentrant
| libvirt/ci/helper:33:default=os.getlogin(), # exempt from
syntax-check
| libvirt/include/libvirt/libvirt-storage.h:223:
VIR_STORAGE_VOL_WIPE_ALG_PFITZNER7 = 6, /* 7-pass random (Since: v1.0.0) */
| libvirt/include/libvirt/libvirt-storage.h:225:
VIR_STORAGE_VOL_WIPE_ALG_PFITZNER33 = 7, /* 33-pass random (Since: v1.0.0) */
| libvirt/include/libvirt/libvirt-storage.h:227:
VIR_STORAGE_VOL_WIPE_ALG_RANDOM = 8, /* 1-pass random (Since: v1.0.0) */
Signed-off-by: Victor Toso
---
build-aux/syntax-check.mk | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/build-aux/syntax-check.mk b/build-aux/syntax-check.mk
index a6e3ada300..eb403f3d3f 100644
--- a/build-aux/syntax-check.mk
+++ b/build-aux/syntax-check.mk
@@ -300,7 +300,7 @@ sc_prohibit_PATH_MAX:
include $(top_srcdir)/build-aux/Makefile.nonreentrant
sc_prohibit_nonreentrant:
@prohibit="\\<(${NON_REENTRANT_RE}) *\\(" \
- exclude='exempt from syntax-check' \
+ exclude='exempt from syntax-check|\/\*.*\*\/' \
halt="use re-entrant functions (usually ending with _r)" \
$(_sc_search_regexp)
--
2.35.1
[PATCH v3 02/30] syntax-check: prohibit_virXXXFree: skip strings
We should allow strings (not the functions) in the format of "virDomainFree" and friends. This fixes an error in latter commit "scripts: apibuild: parse 'Since' for functions" as it uses this function names as keys in a dictionary. Fixes: | ... | prohibit_virXXXFree | libvirt/scripts/apibuild.py:163:'virDomainFree': '0.0.1', | make: Leaving directory '/home/toso/src/libvirt/build/build-aux' | stderr: | build-aux/syntax-check.mk: avoid using virXXXFree, use virObjectUnref instead | make: *** [libvirt/build-aux/syntax-check.mk:829: sc_prohibit_virXXXFree] Error 1 Signed-off-by: Victor Toso --- build-aux/syntax-check.mk | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/build-aux/syntax-check.mk b/build-aux/syntax-check.mk index eb403f3d3f..07e0295995 100644 --- a/build-aux/syntax-check.mk +++ b/build-aux/syntax-check.mk @@ -827,7 +827,7 @@ sc_prohibit_system_error_with_vir_err: # docs, examples, tools, src/libvirt-*.c, and include/libvirt/libvirt-*.h sc_prohibit_virXXXFree: @prohibit='\bvir(Domain|Network|NodeDevice|StorageVol|StoragePool|Stream|Secret|NWFilter|Interface|DomainSnapshot)Free\b' \ - exclude='sc_prohibit_virXXXFree' \ + exclude="sc_prohibit_virXXXFree|'vir.*?Free'" \ halt='avoid using virXXXFree, use virObjectUnref instead' \ $(_sc_search_regexp) -- 2.35.1
[PATCH v3 00/30] Add 'version' to other exported types
Hi, Here it comes, version 3. v1: https://listman.redhat.com/archives/libvir-list/2022-April/229881.html v2: https://listman.redhat.com/archives/libvir-list/2022-April/230097.html In this version, I have: - dropped the changes to .sym files (Peter, Daniel) - improved commit log: 'doc' -> 'docstring' (and more) (Peter) - fixed all versions prior to v1.0.0 (Peter, Andrea) - created a validate script, to confirm all is good. Not expecting it to be merged, just added to help review that the outcome is acceptable. - lots of fixes found by the script above. - dropped the concept of generated/manual in git shortlog of the series. - added an allow list for functions where there is a mismatch between version in the sym file and the git tag they were introduced (Peter) I hope that it'll be useful to other generators, besides: https://gitlab.com/libvirt/libvirt-go-module/-/merge_requests/7 Gitlab run of this series (fails with codestyle of do-not-commit script). https://gitlab.com/victortoso/libvirt/-/pipelines/520901763 Have a wonderful day, Victor Victor Toso (30): syntax-check: sc_prohibit_nonreentrant: skip comments syntax-check: prohibit_virXXXFree: skip strings docstring: Fix generated documentation of virConnectListAllNodeDeviceFlags docstring: variable: Move docstring from source to header file docstring: enums: libvirt: Add 'Since version' metadata docstring: enums: qemu: Add 'Since version' metadata docstring: enums: admin: Add 'Since version' metadata docstring: macros: libvirt: Add 'Since version' metadata docstring: macros: admin: Add 'Since version' metadata docstring: typedef: libvirt:: Add 'Since version' metadata docstring: typedef: qemu:: Add 'Since version' metadata docstring: typedef: admin:: Add 'Since version' metadata docstring: function: libvirt: Add 'Since version' metadata docstring: function: qemu: Add 'Since version' metadata docstring: function: lxc: Add 'Since version' metadata docstring: function: admin: Add 'Since version' metadata docstring: libvirt-common: Add 'Since version' metadata docstring: Fix generated documentation of virStorageVolInfoFlags docstring: Fix and append Since to virConnectListAllStoragePoolsFlags docstring: Fix and append Since to virDomainDeviceModifyFlags docstring: Fix and append Since to virDomainMemoryModFlags docstring: Fix and append Since to virDomainVcpuFlags scripts: apibuild: parse 'Since' version for enums scripts: apibuild: fix parsing block comments from typedef enum scripts: apibuild: parse 'Since' for typedefs scripts: apibuild: parse 'Since' for macros scripts: apibuild: parse 'Since' for functions scripts: apibuild: factor out comment cleaning scripts: apibuild: add parsing variable's comments do-not-commit: script to validate output build-aux/syntax-check.mk |4 +- include/libvirt/libvirt-admin.h | 95 +- include/libvirt/libvirt-common.h.in | 54 +- include/libvirt/libvirt-domain-checkpoint.h | 62 +- include/libvirt/libvirt-domain-snapshot.h | 100 +- include/libvirt/libvirt-domain.h| 2665 +++ include/libvirt/libvirt-event.h | 35 +- include/libvirt/libvirt-host.h | 320 ++- include/libvirt/libvirt-interface.h | 33 +- include/libvirt/libvirt-network.h | 195 +- include/libvirt/libvirt-nodedev.h | 100 +- include/libvirt/libvirt-nwfilter.h | 29 +- include/libvirt/libvirt-qemu.h | 39 +- include/libvirt/libvirt-secret.h| 81 +- include/libvirt/libvirt-storage.h | 316 ++- include/libvirt/libvirt-stream.h| 48 +- include/libvirt/virterror.h | 428 +-- scripts/apibuild.py | 212 +- scripts/version-quest.py| 190 ++ src/admin/libvirt-admin.c | 93 + src/libvirt-domain-checkpoint.c | 36 + src/libvirt-domain-snapshot.c | 63 + src/libvirt-domain.c| 557 +++- src/libvirt-host.c | 102 + src/libvirt-interface.c | 63 + src/libvirt-lxc.c | 12 + src/libvirt-network.c | 135 + src/libvirt-nodedev.c | 81 + src/libvirt-nwfilter.c | 72 + src/libvirt-qemu.c | 18 + src/libvirt-secret.c| 60 + src/libvirt-storage.c | 171 ++ src/libvirt-stream.c| 51 + src/libvirt.c | 29 +- src/util/virerror.c | 45 + src/util/virevent.c | 27 + src/util/virtypedparam-public.c | 57 + 37 files changed, 5533 insertions(+), 1145 deletions(-) create mode 100644
[PATCH] apparmor: Allow swtpm to use its own apparmor profile
binj1uIU4i9EZ.bin Description: Binary data
Re: [PATCH 1/2] qemu_processpriv: Fix #error message
On 4/14/22 16:44, Michal Privoznik wrote: > The point of qemu_processpriv.h file is to allow a small subset > of functions to be called from test suite but not elsewhere. This > is implemented by requiring everybody that includes the file to > define a macro. If not done so, an error is printed at compile > time. However, this error message contains a typo because it > mentions qemu_process_priv.h while the file is called > qemu_processpriv.h. > > Signed-off-by: Michal Privoznik > --- > src/qemu/qemu_processpriv.h | 2 +- > 1 file changed, 1 insertion(+), 1 deletion(-) > BTW: I've pushed this as trivial. Michal
Re: virThread: why no return values permitted in thread API?
On Wed, Apr 20, 2022 at 02:24:39PM +0200, Claudio Fontana wrote: > Hi, > > I noticed that in the virThread API return values from threads are explicitly > excluded from the API. > > The "virThreadHelper" sits in the middle between the caller of > virThreadCreate and pthread, making it impossible to return a > value from the thread, to check after joining the thread. Mostly a historical artifact from when we had a native impl of threads for Win32. We didn't need that ability, so I never bothered to try to figure it out for Win32 and thus for consistency I left it out of POSIX impl too. With regards, Daniel -- |: https://berrange.com -o-https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o-https://fstop138.berrange.com :| |: https://entangle-photo.org-o-https://www.instagram.com/dberrange :|
Re: virThread: why no return values permitted in thread API?
On 4/20/22 14:24, Claudio Fontana wrote: > Hi, > > I noticed that in the virThread API return values from threads are explicitly > excluded from the API. > > The "virThreadHelper" sits in the middle between the caller of > virThreadCreate and pthread, making it impossible to return a value from the > thread, > to check after joining the thread. > > I'd need to know if the thread execution is successful or not then I join the > thread, > so what is the reason for this choice? > > Should I use pthread directly instead? Not at all. Just change the type of virThreadJoin(). At which point it's harder to distinguish whether thread ran and returned a value, or thread did not run/exited before the callback was called and retval we are seeing comes from virThreadHelper(), but since it does not return anything yet, it's easy to distinguish the two. Whatever you do, please avoid using pthread directly. Michal
Re: virThread: why no return values permitted in thread API?
On Wed, Apr 20, 2022 at 02:33:19PM +0200, Peter Krempa wrote: > On Wed, Apr 20, 2022 at 14:24:39 +0200, Claudio Fontana wrote: > > Hi, > > > > I noticed that in the virThread API return values from threads are > > explicitly excluded from the API. > > > > The "virThreadHelper" sits in the middle between the caller of > > virThreadCreate and pthread, making it impossible to return a value from > > the thread, > > to check after joining the thread. > > virThreadCreate has an 'opaque' parameter which allows to pass arbitrary > data to the trhead. You can use it to pass also data back, just apply > thread safety rules. > > > I'd need to know if the thread execution is successful or not then I join > > the thread, > > so what is the reason for this choice? > > Could you elaborate what you are trying to achieve? > > > Should I use pthread directly instead? > > Generally no, please use the internal helpers for code consistency. Though we should really be phasing out much of virthread.h in favour of just using GLib's portable thread APIs. So personally I'd be fine with patches that use GThread in new code. With regards, Daniel -- |: https://berrange.com -o-https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o-https://fstop138.berrange.com :| |: https://entangle-photo.org-o-https://www.instagram.com/dberrange :|
Re: [PATCH v2 1/8] Make NVRAM a virStorageSource type.
On Fri, Apr 08, 2022 at 10:48:44 -0700, Rohit Kumar wrote:
> Currently, libvirt allows only local filepaths to specify
> a NVRAM disk. Since, VMs can migrate across hosts, so making
Note that this is not strictly needed for migration to work. In fact
qemu migratest he contents of the nvram inside the migration stream and
flushes it out on the destination, thus migration will work as expected
even when the storage is backed locally.
> it to virStorageSource type would help in uninturrupted access
> NVRAM disks over network.
Thus this statement is not accurate.
I understand though that this gives you the flexibility to start the VM
on any host without having to worry about where to get the latest nvram
image.
> Signed-off-by: Prerna Saxena
> Signed-off-by: Florian Schmidt
> Signed-off-by: Rohit Kumar
> ---
> src/conf/domain_conf.c | 13 ++---
> src/conf/domain_conf.h | 2 +-
> src/qemu/qemu_cgroup.c | 3 ++-
> src/qemu/qemu_command.c | 2 +-
> src/qemu/qemu_domain.c | 14 --
> src/qemu/qemu_driver.c | 5 +++--
> src/qemu/qemu_firmware.c| 17 -
> src/qemu/qemu_namespace.c | 5 +++--
> src/qemu/qemu_process.c | 5 +++--
> src/security/security_dac.c | 6 --
> src/security/security_selinux.c | 6 --
> src/security/virt-aa-helper.c | 5 +++--
> src/vbox/vbox_common.c | 2 +-
> 13 files changed, 55 insertions(+), 30 deletions(-)
[...]
> @@ -18266,7 +18266,11 @@ virDomainDefParseBootLoaderOptions(virDomainDef *def,
> fwAutoSelect) < 0)
> return -1;
>
> -def->os.loader->nvram = virXPathString("string(./os/nvram[1])", ctxt);
> +if (virXPathNode("./os/nvram[1]", ctxt)) {
> +def->os.loader->nvram = g_new0(virStorageSource, 1);
[1]
This is wrong. virStorageSource is an virObject instance so allocating
it like this doesn't initialize the virObject part.
You must use virStorageSourceNew exclusively to do this.
> +def->os.loader->nvram->path =
> virXPathString("string(./os/nvram[1])", ctxt);
> +def->os.loader->nvram->type = VIR_STORAGE_TYPE_FILE;
> +}
> if (!fwAutoSelect)
> def->os.loader->nvramTemplate =
> virXPathString("string(./os/nvram[1]/@template)", ctxt);
>
[...]
> diff --git a/src/qemu/qemu_cgroup.c b/src/qemu/qemu_cgroup.c
> index aa0c927578..d46c9ff36a 100644
> --- a/src/qemu/qemu_cgroup.c
> +++ b/src/qemu/qemu_cgroup.c
> @@ -581,7 +581,8 @@ qemuSetupFirmwareCgroup(virDomainObj *vm)
> return -1;
>
> if (vm->def->os.loader->nvram &&
> -qemuSetupImagePathCgroup(vm, vm->def->os.loader->nvram, false) < 0)
> +vm->def->os.loader->nvram->type == VIR_STORAGE_TYPE_FILE &&
[1]
This is not future proof, this should rather use
'virStorageSourceIsLocalStorage()' so that it also covers cases when
e.g. user deliberately selects a 'block' backed nvram.
> +qemuSetupImagePathCgroup(vm, vm->def->os.loader->nvram->path, false)
> < 0)
> return -1;
>
> return 0;
[...]
> diff --git a/src/qemu/qemu_domain.c b/src/qemu/qemu_domain.c
> index a4334de158..70e96cc5a5 100644
> --- a/src/qemu/qemu_domain.c
> +++ b/src/qemu/qemu_domain.c
> @@ -4663,8 +4663,12 @@ qemuDomainDefPostParse(virDomainDef *def,
> }
>
> if (virDomainDefHasOldStyleROUEFI(def) &&
> -!def->os.loader->nvram)
> -qemuDomainNVRAMPathFormat(cfg, def, >os.loader->nvram);
> +(!def->os.loader->nvram || !def->os.loader->nvram->path)) {
> +if (!def->os.loader->nvram)
> +def->os.loader->nvram = g_new0(virStorageSource, 1);
See [1]
> +def->os.loader->nvram->type = VIR_STORAGE_TYPE_FILE;
> +qemuDomainNVRAMPathFormat(cfg, def, >os.loader->nvram->path);
> +}
>
> if (qemuDomainDefAddDefaultDevices(driver, def, qemuCaps) < 0)
> return -1;
[...]
> diff --git a/src/qemu/qemu_driver.c b/src/qemu/qemu_driver.c
> index 8c0e36e9b2..2b2bd8d20c 100644
> --- a/src/qemu/qemu_driver.c
> +++ b/src/qemu/qemu_driver.c
> @@ -6615,8 +6615,9 @@ qemuDomainUndefineFlags(virDomainPtr dom,
> }
> }
>
> -if (vm->def->os.loader && vm->def->os.loader->nvram) {
> -nvram_path = g_strdup(vm->def->os.loader->nvram);
> +if (vm->def->os.loader && vm->def->os.loader->nvram &&
> +vm->def->os.loader->nvram->type == VIR_STORAGE_TYPE_FILE) {
> +nvram_path = g_strdup(vm->def->os.loader->nvram->path);
Consider [2].
> } else if (vm->def->os.firmware == VIR_DOMAIN_OS_DEF_FIRMWARE_EFI) {
> qemuDomainNVRAMPathFormat(cfg, vm->def, _path);
> }
> diff --git a/src/qemu/qemu_firmware.c b/src/qemu/qemu_firmware.c
> index 51223faadf..6556a613a8 100644
> --- a/src/qemu/qemu_firmware.c
> +++ b/src/qemu/qemu_firmware.c
> @@ -1192,13 +1192,16 @@ qemuFirmwareEnableFeatures(virQEMUDriver *driver,
> VIR_FREE(def->os.loader->nvramTemplate);
>
Re: [PATCH] tests: qemucapabilities: Update qemu caps dump for the qemu-7.0.0 release on x86_64
On Wed, 20 Apr 2022 14:13:00 +0200 Peter Krempa wrote: > On Wed, Apr 20, 2022 at 14:00:52 +0200, Igor Mammedov wrote: > > On Wed, 20 Apr 2022 12:21:03 +0100 > > Daniel P. Berrangé wrote: > > > > > On Wed, Apr 20, 2022 at 01:15:43PM +0200, Igor Mammedov wrote: > > > > On Wed, 20 Apr 2022 13:02:12 +0200 > > > > Peter Krempa wrote: > > > > > > > > > Few minor changes in qemu since the last update: > > > > > - PIIX4_PM gained 'x-not-migrate-acpi-index' property > > > > > > > > do you do this for just for every new property? > > > > (nothing outside of QEMU needs to know about x-not-migrate-acpi-index, > > > > unless one is interested in whether it works or not) > > > > > > This is simply a record of what QEMU reports when you query properties > > > for the devices libvirt cares about. > > > > I was just curious why libvirt does it. > > > > > If nothing outside is supposed to > > > know about x-not-migrate-acpi-index then QEMU shouldn't tell us about > > > it when asked for properties :-) > > > > Does livirt uses/exposes x- prefixed property anywhere? > > (i.e. can QEMU hide them?) > > I don't think it's needed to hide them. In fact we have strong rules > against using them. > > With one notable exception: > > -object memory-backend-file,x-use-canonical-path-for-ramblock-id= > > But this was discussed extensively on the qemu list and qemu pledges > that this specific property is considered stable. ok lets leave it as is.
Re: virThread: why no return values permitted in thread API?
On Wed, Apr 20, 2022 at 14:24:39 +0200, Claudio Fontana wrote: > Hi, > > I noticed that in the virThread API return values from threads are explicitly > excluded from the API. > > The "virThreadHelper" sits in the middle between the caller of > virThreadCreate and pthread, making it impossible to return a value from the > thread, > to check after joining the thread. virThreadCreate has an 'opaque' parameter which allows to pass arbitrary data to the trhead. You can use it to pass also data back, just apply thread safety rules. > I'd need to know if the thread execution is successful or not then I join the > thread, > so what is the reason for this choice? Could you elaborate what you are trying to achieve? > Should I use pthread directly instead? Generally no, please use the internal helpers for code consistency.
virThread: why no return values permitted in thread API?
Hi, I noticed that in the virThread API return values from threads are explicitly excluded from the API. The "virThreadHelper" sits in the middle between the caller of virThreadCreate and pthread, making it impossible to return a value from the thread, to check after joining the thread. I'd need to know if the thread execution is successful or not then I join the thread, so what is the reason for this choice? Should I use pthread directly instead? Thanks, Claudio -- Claudio Fontana Engineering Manager Virtualization, SUSE Labs Core SUSE Software Solutions Italy Srl
Re: [PATCH] tests: qemucapabilities: Update qemu caps dump for the qemu-7.0.0 release on x86_64
On Wed, Apr 20, 2022 at 02:00:52PM +0200, Igor Mammedov wrote: > On Wed, 20 Apr 2022 12:21:03 +0100 > Daniel P. Berrangé wrote: > > > On Wed, Apr 20, 2022 at 01:15:43PM +0200, Igor Mammedov wrote: > > > On Wed, 20 Apr 2022 13:02:12 +0200 > > > Peter Krempa wrote: > > > > > > > Few minor changes in qemu since the last update: > > > > - PIIX4_PM gained 'x-not-migrate-acpi-index' property > > > > > > do you do this for just for every new property? > > > (nothing outside of QEMU needs to know about x-not-migrate-acpi-index, > > > unless one is interested in whether it works or not) > > > > This is simply a record of what QEMU reports when you query properties > > for the devices libvirt cares about. > > I was just curious why libvirt does it. > > > If nothing outside is supposed to > > know about x-not-migrate-acpi-index then QEMU shouldn't tell us about > > it when asked for properties :-) > > Does livirt uses/exposes x- prefixed property anywhere? > (i.e. can QEMU hide them?) No, as a policy libvirt won't touch x- properties from QEMU at all. Note, these data files are just used for unit tests to validate certain parts of libvirt rather than require the actual QEMU binaries to exist during unit tests. With regards, Daniel -- |: https://berrange.com -o-https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o-https://fstop138.berrange.com :| |: https://entangle-photo.org-o-https://www.instagram.com/dberrange :|
Re: [PATCH] tests: qemucapabilities: Update qemu caps dump for the qemu-7.0.0 release on x86_64
On Wed, Apr 20, 2022 at 14:00:52 +0200, Igor Mammedov wrote: > On Wed, 20 Apr 2022 12:21:03 +0100 > Daniel P. Berrangé wrote: > > > On Wed, Apr 20, 2022 at 01:15:43PM +0200, Igor Mammedov wrote: > > > On Wed, 20 Apr 2022 13:02:12 +0200 > > > Peter Krempa wrote: > > > > > > > Few minor changes in qemu since the last update: > > > > - PIIX4_PM gained 'x-not-migrate-acpi-index' property > > > > > > do you do this for just for every new property? > > > (nothing outside of QEMU needs to know about x-not-migrate-acpi-index, > > > unless one is interested in whether it works or not) > > > > This is simply a record of what QEMU reports when you query properties > > for the devices libvirt cares about. > > I was just curious why libvirt does it. > > > If nothing outside is supposed to > > know about x-not-migrate-acpi-index then QEMU shouldn't tell us about > > it when asked for properties :-) > > Does livirt uses/exposes x- prefixed property anywhere? > (i.e. can QEMU hide them?) I don't think it's needed to hide them. In fact we have strong rules against using them. With one notable exception: -object memory-backend-file,x-use-canonical-path-for-ramblock-id= But this was discussed extensively on the qemu list and qemu pledges that this specific property is considered stable.
Re: [PATCH] tests: qemucapabilities: Update qemu caps dump for the qemu-7.0.0 release on x86_64
On Wed, 20 Apr 2022 12:21:03 +0100 Daniel P. Berrangé wrote: > On Wed, Apr 20, 2022 at 01:15:43PM +0200, Igor Mammedov wrote: > > On Wed, 20 Apr 2022 13:02:12 +0200 > > Peter Krempa wrote: > > > > > Few minor changes in qemu since the last update: > > > - PIIX4_PM gained 'x-not-migrate-acpi-index' property > > > > do you do this for just for every new property? > > (nothing outside of QEMU needs to know about x-not-migrate-acpi-index, > > unless one is interested in whether it works or not) > > This is simply a record of what QEMU reports when you query properties > for the devices libvirt cares about. I was just curious why libvirt does it. > If nothing outside is supposed to > know about x-not-migrate-acpi-index then QEMU shouldn't tell us about > it when asked for properties :-) Does livirt uses/exposes x- prefixed property anywhere? (i.e. can QEMU hide them?) > With regards, > Daniel
Re: [PATCH] tests: qemucapabilities: Update qemu caps dump for the qemu-7.0.0 release on x86_64
On Wed, Apr 20, 2022 at 16:52:14 +0530, Ani Sinha wrote: > On Wed, Apr 20, 2022 at 4:46 PM Igor Mammedov wrote: > > > > On Wed, 20 Apr 2022 13:02:12 +0200 > > Peter Krempa wrote: > > > > > Few minor changes in qemu since the last update: > > > - PIIX4_PM gained 'x-not-migrate-acpi-index' property > > > > do you do this for just for every new property? > > (nothing outside of QEMU needs to know about x-not-migrate-acpi-index, > > unless one is interested in whether it works or not) > > Any new property that is prefixed with "x-" should not be exposed > through libvirt. They are experimental, unstable and can change any > time in the future. We don't expose it. I'm just simply noting what changed between the caps dumps. Since the difference between rc2 and GA hadn't much to happen I also noted this.
Re: [PATCH] tests: qemucapabilities: Update qemu caps dump for the qemu-7.0.0 release on x86_64
On Wed, Apr 20, 2022 at 13:15:43 +0200, Igor Mammedov wrote: > On Wed, 20 Apr 2022 13:02:12 +0200 > Peter Krempa wrote: > > > Few minor changes in qemu since the last update: > > - PIIX4_PM gained 'x-not-migrate-acpi-index' property > > do you do this for just for every new property? > (nothing outside of QEMU needs to know about x-not-migrate-acpi-index, > unless one is interested in whether it works or not) I generally go through the diff of things that change and note what's changed. In most cases it's just the interesting stuff, but between rc2 and GA there wasn't much interesting going on.
Re: Network disks and replacing qemu-block-curl|ssh with nbdkit
On Wed, Apr 20, 2022 at 09:52:34 +0100, Richard W.M. Jones wrote: > On Wed, Apr 20, 2022 at 09:36:29AM +0200, Peter Krempa wrote: > > I'll post patches to address that, but the question is whether we want > > to bother with actually supporting the password authentication or not, > > because the simpler approach to fixing the bug is to simply allow it. > > Did you mean: Simply _not_ allow it? No actually code-wise everything seems to be in place. The parser parses it, the -blockdev formatter supports it. The only thing that prevents from use of the authentication with the curl driver backends is a check in a helper function which limits the protocols we instantiate the 'secret' object for. Removing that limit actually makes us pass the secret to qemu and our validator shows that it's valid definition. Adding the schema bits should be easy too.
Re: [PATCH] tests: qemucapabilities: Update qemu caps dump for the qemu-7.0.0 release on x86_64
On Wed, Apr 20, 2022 at 4:46 PM Igor Mammedov wrote:
>
> On Wed, 20 Apr 2022 13:02:12 +0200
> Peter Krempa wrote:
>
> > Few minor changes in qemu since the last update:
> > - PIIX4_PM gained 'x-not-migrate-acpi-index' property
>
> do you do this for just for every new property?
> (nothing outside of QEMU needs to know about x-not-migrate-acpi-index,
> unless one is interested in whether it works or not)
Any new property that is prefixed with "x-" should not be exposed
through libvirt. They are experimental, unstable and can change any
time in the future.
>
> > - 'cocoa' display and corresponding props (not present in this build)
> >
> > Changes in build:
> > - dbus display driver re-enabled
> > - gtk display support re-disabled
> > - xen support re-disabled
> >
> > Signed-off-by: Peter Krempa
> > ---
> > .../caps_7.0.0.x86_64.replies | 583 --
> > .../caps_7.0.0.x86_64.xml | 10 +-
> > 2 files changed, 257 insertions(+), 336 deletions(-)
> >
> > diff --git a/tests/qemucapabilitiesdata/caps_7.0.0.x86_64.replies
> > b/tests/qemucapabilitiesdata/caps_7.0.0.x86_64.replies
> > index d1f453dcca..620442704a 100644
> > --- a/tests/qemucapabilitiesdata/caps_7.0.0.x86_64.replies
> > +++ b/tests/qemucapabilitiesdata/caps_7.0.0.x86_64.replies
> > @@ -17,11 +17,11 @@
> > {
> >"return": {
> > "qemu": {
> > - "micro": 92,
> > - "minor": 2,
> > - "major": 6
> > + "micro": 0,
> > + "minor": 0,
> > + "major": 7
> > },
> > -"package": "v7.0.0-rc2"
> > +"package": "v7.0.0"
> >},
> >"id": "libvirt-2"
> > }
> > @@ -5119,10 +5119,6 @@
> >"name": "135",
> >"tag": "type",
> >"variants": [
> > -{
> > - "case": "gtk",
> > - "type": "358"
> > -},
> > {
> >"case": "curses",
> >"type": "360"
> > @@ -5131,6 +5127,10 @@
> >"case": "egl-headless",
> >"type": "361"
> > },
> > +{
> > + "case": "dbus",
> > + "type": "362"
> > +},
> > {
> >"case": "default",
> >"type": "0"
> > @@ -10498,6 +10498,10 @@
> >"case": "qemu-vdagent",
> >"type": "518"
> > },
> > +{
> > + "case": "dbus",
> > + "type": "519"
> > +},
> > {
> >"case": "vc",
> >"type": "520"
> > @@ -11756,9 +11760,6 @@
> > {
> >"name": "none"
> > },
> > -{
> > - "name": "gtk"
> > -},
> > {
> >"name": "sdl"
> > },
> > @@ -11770,17 +11771,20 @@
> > },
> > {
> >"name": "spice-app"
> > +},
> > +{
> > + "name": "dbus"
> > }
> >],
> >"meta-type": "enum",
> >"values": [
> > "default",
> > "none",
> > -"gtk",
> > "sdl",
> > "egl-headless",
> > "curses",
> > -"spice-app"
> > +"spice-app",
> > +"dbus"
> >]
> > },
> > {
> > @@ -16067,6 +16071,9 @@
> > {
> >"name": "qemu-vdagent"
> > },
> > +{
> > + "name": "dbus"
> > +},
> > {
> >"name": "vc"
> > },
> > @@ -16097,6 +16104,7 @@
> > "spicevmc",
> > "spiceport",
> > "qemu-vdagent",
> > +"dbus",
> > "vc",
> > "ringbuf",
> > "memory"
> > @@ -16202,6 +16210,16 @@
> >],
> >"meta-type": "object"
> > },
> > +{
> > + "name": "519",
> > + "members": [
> > +{
> > + "name": "data",
> > + "type": "618"
> > +}
> > + ],
> > + "meta-type": "object"
> > +},
> > {
> >"name": "520",
> >"members": [
> > @@ -18460,6 +18478,26 @@
> >],
> >"meta-type": "object"
> > },
> > +{
> > + "name": "618",
> > + "members": [
> > +{
> > + "name": "logfile",
> > + "default": null,
> > + "type": "str"
> > +},
> > +{
> > + "name": "logappend",
> > + "default": null,
> > + "type": "bool"
> > +},
> > +{
> > + "name": "name",
> > + "type": "str"
> > +}
> > + ],
> > + "meta-type": "object"
> > +},
> > {
> >"name": "619",
> >"members": [
> > @@ -20363,10 +20401,6 @@
> >"name": "acpi-erst",
> >"parent": "pci-device"
> > },
> > -{
> > - "name": "virtio-crypto-device",
> > - "parent": "virtio-device"
> > -},
> > {
> >"name": "isa-applesmc",
> >"parent": "isa-device"
> > @@ -20379,49 +20413,53 @@
> >"name": "vhost-user-input-pci",
> >"parent": "vhost-user-input-pci-base-type"
> > },
> > +{
>
Re: [PATCH] tests: qemucapabilities: Update qemu caps dump for the qemu-7.0.0 release on x86_64
On Wed, Apr 20, 2022 at 01:15:43PM +0200, Igor Mammedov wrote: > On Wed, 20 Apr 2022 13:02:12 +0200 > Peter Krempa wrote: > > > Few minor changes in qemu since the last update: > > - PIIX4_PM gained 'x-not-migrate-acpi-index' property > > do you do this for just for every new property? > (nothing outside of QEMU needs to know about x-not-migrate-acpi-index, > unless one is interested in whether it works or not) This is simply a record of what QEMU reports when you query properties for the devices libvirt cares about. If nothing outside is supposed to know about x-not-migrate-acpi-index then QEMU shouldn't tell us about it when asked for properties :-) With regards, Daniel -- |: https://berrange.com -o-https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o-https://fstop138.berrange.com :| |: https://entangle-photo.org-o-https://www.instagram.com/dberrange :|
Re: [PATCH] tests: qemucapabilities: Update qemu caps dump for the qemu-7.0.0 release on x86_64
On Wed, 20 Apr 2022 13:02:12 +0200
Peter Krempa wrote:
> Few minor changes in qemu since the last update:
> - PIIX4_PM gained 'x-not-migrate-acpi-index' property
do you do this for just for every new property?
(nothing outside of QEMU needs to know about x-not-migrate-acpi-index,
unless one is interested in whether it works or not)
> - 'cocoa' display and corresponding props (not present in this build)
>
> Changes in build:
> - dbus display driver re-enabled
> - gtk display support re-disabled
> - xen support re-disabled
>
> Signed-off-by: Peter Krempa
> ---
> .../caps_7.0.0.x86_64.replies | 583 --
> .../caps_7.0.0.x86_64.xml | 10 +-
> 2 files changed, 257 insertions(+), 336 deletions(-)
>
> diff --git a/tests/qemucapabilitiesdata/caps_7.0.0.x86_64.replies
> b/tests/qemucapabilitiesdata/caps_7.0.0.x86_64.replies
> index d1f453dcca..620442704a 100644
> --- a/tests/qemucapabilitiesdata/caps_7.0.0.x86_64.replies
> +++ b/tests/qemucapabilitiesdata/caps_7.0.0.x86_64.replies
> @@ -17,11 +17,11 @@
> {
>"return": {
> "qemu": {
> - "micro": 92,
> - "minor": 2,
> - "major": 6
> + "micro": 0,
> + "minor": 0,
> + "major": 7
> },
> -"package": "v7.0.0-rc2"
> +"package": "v7.0.0"
>},
>"id": "libvirt-2"
> }
> @@ -5119,10 +5119,6 @@
>"name": "135",
>"tag": "type",
>"variants": [
> -{
> - "case": "gtk",
> - "type": "358"
> -},
> {
>"case": "curses",
>"type": "360"
> @@ -5131,6 +5127,10 @@
>"case": "egl-headless",
>"type": "361"
> },
> +{
> + "case": "dbus",
> + "type": "362"
> +},
> {
>"case": "default",
>"type": "0"
> @@ -10498,6 +10498,10 @@
>"case": "qemu-vdagent",
>"type": "518"
> },
> +{
> + "case": "dbus",
> + "type": "519"
> +},
> {
>"case": "vc",
>"type": "520"
> @@ -11756,9 +11760,6 @@
> {
>"name": "none"
> },
> -{
> - "name": "gtk"
> -},
> {
>"name": "sdl"
> },
> @@ -11770,17 +11771,20 @@
> },
> {
>"name": "spice-app"
> +},
> +{
> + "name": "dbus"
> }
>],
>"meta-type": "enum",
>"values": [
> "default",
> "none",
> -"gtk",
> "sdl",
> "egl-headless",
> "curses",
> -"spice-app"
> +"spice-app",
> +"dbus"
>]
> },
> {
> @@ -16067,6 +16071,9 @@
> {
>"name": "qemu-vdagent"
> },
> +{
> + "name": "dbus"
> +},
> {
>"name": "vc"
> },
> @@ -16097,6 +16104,7 @@
> "spicevmc",
> "spiceport",
> "qemu-vdagent",
> +"dbus",
> "vc",
> "ringbuf",
> "memory"
> @@ -16202,6 +16210,16 @@
>],
>"meta-type": "object"
> },
> +{
> + "name": "519",
> + "members": [
> +{
> + "name": "data",
> + "type": "618"
> +}
> + ],
> + "meta-type": "object"
> +},
> {
>"name": "520",
>"members": [
> @@ -18460,6 +18478,26 @@
>],
>"meta-type": "object"
> },
> +{
> + "name": "618",
> + "members": [
> +{
> + "name": "logfile",
> + "default": null,
> + "type": "str"
> +},
> +{
> + "name": "logappend",
> + "default": null,
> + "type": "bool"
> +},
> +{
> + "name": "name",
> + "type": "str"
> +}
> + ],
> + "meta-type": "object"
> +},
> {
>"name": "619",
>"members": [
> @@ -20363,10 +20401,6 @@
>"name": "acpi-erst",
>"parent": "pci-device"
> },
> -{
> - "name": "virtio-crypto-device",
> - "parent": "virtio-device"
> -},
> {
>"name": "isa-applesmc",
>"parent": "isa-device"
> @@ -20379,49 +20413,53 @@
>"name": "vhost-user-input-pci",
>"parent": "vhost-user-input-pci-base-type"
> },
> +{
> + "name": "usb-redir",
> + "parent": "usb-device"
> +},
> {
>"name": "floppy-bus",
>"parent": "bus"
> },
> {
> - "name": "Denverton-x86_64-cpu",
> - "parent": "x86_64-cpu"
> + "name": "virtio-crypto-device",
> + "parent": "virtio-device"
> },
> {
>"name": "chardev-testdev",
>"parent": "chardev"
> },
> {
> - "name": "usb-wacom-tablet",
> - "parent": "usb-device"
> + "name": "Denverton-x86_64-cpu",
> + "parent": "x86_64-cpu"
> },
> {
> -
[PATCH] tests: qemucapabilities: Update qemu caps dump for the qemu-7.0.0 release on x86_64
Few minor changes in qemu since the last update:
- PIIX4_PM gained 'x-not-migrate-acpi-index' property
- 'cocoa' display and corresponding props (not present in this build)
Changes in build:
- dbus display driver re-enabled
- gtk display support re-disabled
- xen support re-disabled
Signed-off-by: Peter Krempa
---
.../caps_7.0.0.x86_64.replies | 583 --
.../caps_7.0.0.x86_64.xml | 10 +-
2 files changed, 257 insertions(+), 336 deletions(-)
diff --git a/tests/qemucapabilitiesdata/caps_7.0.0.x86_64.replies
b/tests/qemucapabilitiesdata/caps_7.0.0.x86_64.replies
index d1f453dcca..620442704a 100644
--- a/tests/qemucapabilitiesdata/caps_7.0.0.x86_64.replies
+++ b/tests/qemucapabilitiesdata/caps_7.0.0.x86_64.replies
@@ -17,11 +17,11 @@
{
"return": {
"qemu": {
- "micro": 92,
- "minor": 2,
- "major": 6
+ "micro": 0,
+ "minor": 0,
+ "major": 7
},
-"package": "v7.0.0-rc2"
+"package": "v7.0.0"
},
"id": "libvirt-2"
}
@@ -5119,10 +5119,6 @@
"name": "135",
"tag": "type",
"variants": [
-{
- "case": "gtk",
- "type": "358"
-},
{
"case": "curses",
"type": "360"
@@ -5131,6 +5127,10 @@
"case": "egl-headless",
"type": "361"
},
+{
+ "case": "dbus",
+ "type": "362"
+},
{
"case": "default",
"type": "0"
@@ -10498,6 +10498,10 @@
"case": "qemu-vdagent",
"type": "518"
},
+{
+ "case": "dbus",
+ "type": "519"
+},
{
"case": "vc",
"type": "520"
@@ -11756,9 +11760,6 @@
{
"name": "none"
},
-{
- "name": "gtk"
-},
{
"name": "sdl"
},
@@ -11770,17 +11771,20 @@
},
{
"name": "spice-app"
+},
+{
+ "name": "dbus"
}
],
"meta-type": "enum",
"values": [
"default",
"none",
-"gtk",
"sdl",
"egl-headless",
"curses",
-"spice-app"
+"spice-app",
+"dbus"
]
},
{
@@ -16067,6 +16071,9 @@
{
"name": "qemu-vdagent"
},
+{
+ "name": "dbus"
+},
{
"name": "vc"
},
@@ -16097,6 +16104,7 @@
"spicevmc",
"spiceport",
"qemu-vdagent",
+"dbus",
"vc",
"ringbuf",
"memory"
@@ -16202,6 +16210,16 @@
],
"meta-type": "object"
},
+{
+ "name": "519",
+ "members": [
+{
+ "name": "data",
+ "type": "618"
+}
+ ],
+ "meta-type": "object"
+},
{
"name": "520",
"members": [
@@ -18460,6 +18478,26 @@
],
"meta-type": "object"
},
+{
+ "name": "618",
+ "members": [
+{
+ "name": "logfile",
+ "default": null,
+ "type": "str"
+},
+{
+ "name": "logappend",
+ "default": null,
+ "type": "bool"
+},
+{
+ "name": "name",
+ "type": "str"
+}
+ ],
+ "meta-type": "object"
+},
{
"name": "619",
"members": [
@@ -20363,10 +20401,6 @@
"name": "acpi-erst",
"parent": "pci-device"
},
-{
- "name": "virtio-crypto-device",
- "parent": "virtio-device"
-},
{
"name": "isa-applesmc",
"parent": "isa-device"
@@ -20379,49 +20413,53 @@
"name": "vhost-user-input-pci",
"parent": "vhost-user-input-pci-base-type"
},
+{
+ "name": "usb-redir",
+ "parent": "usb-device"
+},
{
"name": "floppy-bus",
"parent": "bus"
},
{
- "name": "Denverton-x86_64-cpu",
- "parent": "x86_64-cpu"
+ "name": "virtio-crypto-device",
+ "parent": "virtio-device"
},
{
"name": "chardev-testdev",
"parent": "chardev"
},
{
- "name": "usb-wacom-tablet",
- "parent": "usb-device"
+ "name": "Denverton-x86_64-cpu",
+ "parent": "x86_64-cpu"
},
{
- "name": "Icelake-Server-v1-x86_64-cpu",
- "parent": "x86_64-cpu"
+ "name": "pci-ipmi-bt",
+ "parent": "pci-device"
},
{
"name": "chardev-stdio",
"parent": "chardev-fd"
},
{
- "name": "pci-ipmi-bt",
- "parent": "pci-device"
+ "name": "usb-wacom-tablet",
+ "parent": "usb-device"
},
{
"name": "filter-buffer",
"parent": "netfilter"
},
{
- "name": "secondary-vga",
- "parent": "pci-vga"
+ "name": "Icelake-Server-v1-x86_64-cpu",
+ "parent": "x86_64-cpu"
},
{
"name": "ich9-usb-uhci6",
"parent":
Re: [PATCH] apparmor: Allow swtpm to use its own apparmor profile
On Tue, Apr 19, 2022 at 7:28 PM Lena Voytek wrote:
Hi Lena,
the code is fine - I can confirm that this works well in Ubuntu 22.04 already.
But we should add a non-empty commit message here.
Just outline that this is needed when swtpm itself runs under a
profile called "swtpm".
And maybe reference the upstreaming of that profile into the swtpm project.
P.S. also adding Jim to CC as he looks at apparmor from Suses POV sometimes.
> Signed-off-by: Lena Voytek
> ---
> src/security/apparmor/libvirt-qemu | 3 ++-
> src/security/apparmor/usr.sbin.libvirtd.in | 1 +
> 2 files changed, 3 insertions(+), 1 deletion(-)
>
> diff --git a/src/security/apparmor/libvirt-qemu
> b/src/security/apparmor/libvirt-qemu
> index 250ba4ea58..c29168da27 100644
> --- a/src/security/apparmor/libvirt-qemu
> +++ b/src/security/apparmor/libvirt-qemu
> @@ -180,7 +180,7 @@
>audit deny /{var/,}run/qemu/*/*.so w,
>
># swtpm
> - /{usr/,}bin/swtpm rmix,
> + /{usr/,}bin/swtpm rmpix,
>/usr/{lib,lib64}/libswtpm_libtpms.so mr,
>/usr/lib/@{multiarch}/libswtpm_libtpms.so mr,
>
> @@ -226,6 +226,7 @@
>unix (send, receive) type=stream addr=none peer=(label=libvirtd),
>unix (send, receive) type=stream addr=none peer=(label=/usr/sbin/libvirtd),
>unix (send, receive) type=stream addr=none peer=(label=virtqemud),
> + unix (send, receive) type=stream addr=none peer=(label=swtpm),
>
># for gathering information about available host resources
>/sys/devices/system/cpu/ r,
> diff --git a/src/security/apparmor/usr.sbin.libvirtd.in
> b/src/security/apparmor/usr.sbin.libvirtd.in
> index f2ab6ff2aa..886f1ad518 100644
> --- a/src/security/apparmor/usr.sbin.libvirtd.in
> +++ b/src/security/apparmor/usr.sbin.libvirtd.in
> @@ -58,6 +58,7 @@ profile libvirtd @sbindir@/libvirtd
> flags=(attach_disconnected) {
>ptrace (read,trace) peer=dnsmasq,
>ptrace (read,trace) peer=/usr/sbin/dnsmasq,
>ptrace (read,trace) peer=libvirt-*,
> + ptrace (read,trace) peer=swtpm,
>
>signal (send) peer=dnsmasq,
>signal (send) peer=/usr/sbin/dnsmasq,
> --
> 2.25.1
>
--
Christian Ehrhardt
Staff Engineer, Ubuntu Server
Canonical Ltd
Re: [RFC PATCH v1 0/5] Add virDomainGetSevAttestationReport API
On Thu, Apr 14, 2022 at 02:46:38PM -0400, Tyler Fanelli wrote:
> On 4/11/22 10:57 AM, Cole Robinson wrote:
> > On 3/23/22 3:36 PM, Tyler Fanelli wrote:
> > > This an RFC discussing a new API, virDomainGetSevAttestationReport (along
> > > with a
> > > virsh command "domgetsevreport"), with initial QEMU support via the
> > > "query-sev-attestation-report" QAPI mechanism.
> > > "query-sev-attestation-report" is
> > > supplied a base64-encoded 16 byte "mnonce" string as input, with a
> > > purpose of
> > > being embedded into the attestation report to provide protection.
> > >
> > > My main point of concern is the design/communication of the
> > > virTypedParameterPtr
> > > exchanged between the client and libvirtd and how they interact together,
> > > as I
> > > have seen no other API follow the method I used. Namely, the same
> > > virTypedParameterPtr is used for both input _AND_ output. The same
> > > virTypedParameterPtr containing the original mnonce string inputted to
> > > the API is
> > > also used to contain the attestation report upon being returned from the
> > > API.
> > >
> > > This contrasts with much of the APIs I've noticed, which use a
> > > virTypedParameterPtr for either input or output, but not both.
> > >
> > > This patch is not final, as I still would like some human-readable
> > > outputting
> > > and storage of the attestation report.
> > >
> > > Looking for thoughts on the design of this API, as well as suggested
> > > improvements.
> > The proposed API name contains Sev, when all the existing domain APIs
> > have generic names: virDomainGetLaunchSecurityInfo,
> > virDomainSetLaunchSecurityState.
> >
> > I was thinking it would be nice to avoid that Sev specific bit. So I
> > looked at upcoming SNP and TDX qemu patches to see if they add any qmp
> > commands that take input and return a lot of output. Then maybe it would
> > make sense to name this something like
> > virDomainGetLaunchSecurityInfoWithParams which we could use more in the
> > future.
> >
> > qemu SNP patches: https://github.com/AMDESE/qemu/tree/snp-v3
> > - Only extend existing query-sev and query-sev-capabilities
> >
> > qemu TDX patches: https://github.com/intel/qemu-tdx
> > - Adds query-tdx and query-tdx-capabilities, both with no input
> >
> > So, that doesn't help.
>
> What about adding the attestation report to virDomainGetLaunchSecurityInfo?
> If that route is taken, there would probably need to be some extra logic
> added to decipher getting launch security info on SEV vs. SGX/TDX, right?
>
> >
> >
> > After that, my question is, what query-sev-attestation-report adds. The
> > kernel commit explains what it is:
> > https://github.com/torvalds/linux/commit/2c07ded06427dd3339278487a1413d5e478f05f9
> >
> > > The SEV FW version >= 0.23 added a new command that can be used to
> > > query
> > > the attestation report containing the SHA-256 digest of the guest
> > > memory
> > > encrypted through the KVM_SEV_LAUNCH_UPDATE_{DATA, VMSA} commands and
> > > sign the report with the Platform Endorsement Key (PEK).
> > > See the SEV FW API spec section 6.8 for more details.
> > > Note there already exist a command (KVM_SEV_LAUNCH_MEASURE) that can
> > > be
> > > used to get the SHA-256 digest. The main difference between the
> > > KVM_SEV_LAUNCH_MEASURE and KVM_SEV_ATTESTATION_REPORT is that the
> > > latter
> > > can be called while the guest is running and the measurement value is
> > > signed with PEK.
> > So it is LAUNCH_MEASURE, available at VM runtime, signed with an extra key.
> >
> > qemu caches the LAUNCH_MEASURE value at VM startup and lets us query it
> > with qmp any time, so I don't think runtime access matters.
>
> I'm surprised by this. I was under the impression that LAUNCH_MEASURE always
> had to be called when a VM is paused.
Yep, QEMU registers a callback that fetches the launch measurement
from SEV platform when the machine init is done. The query-sev-launch-measure
command always returns cached data, so there's no restriction on when we can
call it from QEMU.
> > Maybe the extra key signing is a security fix or something. I haven't
> > figured it out.
>
> Signing with the PEK also allows a user to verify the root of trust between
> the owner and the platform.
The guest owner needs to acquire the PDH before they launch their guest,
in order to generate the launch blob. The PDH is signed with the PEK,
so they will have surely verified the root of trust with the platform
before they even generate the launch blob for the VM. The generated
launch blob can't be used on any other host, because the other host
won't have the same PDH.
If the launch measurement is signed with the PEK, the guest owner has
the option of postponing their validation of the root of trust until
after the VM is launched. Is that something we need to be able to
deal with ? I'm not sure why one would want to postpone validation
gven that we're already
Re: [PATCH v2 32/34] syms: admin: Add sections to match when API was introduced
On Tue, Apr 19, 2022 at 03:26:45PM +0200, Peter Krempa wrote: > On Thu, Apr 14, 2022 at 22:47:43 +0200, Victor Toso wrote: > > Discover this mismatch with the docstring work. > > scripts/apibuild.py complained. > > > > Signed-off-by: Victor Toso > > --- > > src/admin/libvirt_admin_public.syms | 58 ++--- > > 1 file changed, 45 insertions(+), 13 deletions(-) > > As noted in the reply to the cover letter: > > NACK, this breaks existing builds of apps which link against the admin > client library: Further, the current .syms file is actually correct, though it may not be obvious if you look at git history. We comitted stuff incrementally in earlier versions, but it was not actually consumable by apps until 2.0.0, hence the version was set to 2.0.0 by: commit 52dbacc07a693e14079c445ec677ab03a0888106 Author: Erik Skultety Date: Fri Jun 24 19:27:09 2016 +0200 admin: enable both admin API functionality and tarball distribution This patch enables admin socket creation in daemon's code, bumps the library version in libvirt_admin_public.syms, and performs all necessary modifications to our makefiles so that admin API can finally be included in the tarball, and eventually become part of an rpm package (a patch later in this series). Signed-off-by: Erik Skultety With regards, Daniel -- |: https://berrange.com -o-https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o-https://fstop138.berrange.com :| |: https://entangle-photo.org-o-https://www.instagram.com/dberrange :|
Re: Network disks and replacing qemu-block-curl|ssh with nbdkit
On Wed, Apr 20, 2022 at 09:36:29AM +0200, Peter Krempa wrote: > I'll post patches to address that, but the question is whether we want > to bother with actually supporting the password authentication or not, > because the simpler approach to fixing the bug is to simply allow it. Did you mean: Simply _not_ allow it? Rich. -- Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones Read my programming and virtualization blog: http://rwmj.wordpress.com virt-p2v converts physical machines to virtual machines. Boot with a live CD or over the network (PXE) and turn machines into KVM guests. http://libguestfs.org/virt-v2v
Re: Network disks and replacing qemu-block-curl|ssh with nbdkit
On Tue, Apr 19, 2022 at 15:00:58 -0500, Jonathon Jongsma wrote: > On 4/19/22 12:31 PM, Richard W.M. Jones wrote: > > On Tue, Apr 19, 2022 at 11:40:49AM -0500, Jonathon Jongsma wrote: > > > Well, As far as I can tell, there is no valid XML for exercising > > > http auth. The schema for http(s) sources does not include any > > > element [1]. And the schema for the element [2] > > > requires a element with a required 'type' attribute, and > > > the only choices for 'type' are 'ceph' or 'iscsi', neither of which > > > apply to http authentication. > > > > > > So it looks to me like http auth was never supported, rather than a > > > regression. It also seems that it would require some additional > > > schema changes to support this. > > > > > > > > > [1] > > > https://gitlab.com/libvirt/libvirt/-/blob/136b821f183deb0b58c571211f6917985bed3308/src/conf/schemas/domaincommon.rng#L1974 > > > > > > [2]https://gitlab.com/libvirt/libvirt/-/blob/136b821f183deb0b58c571211f6917985bed3308/src/conf/schemas/domaincommon.rng#L6969 > > > > As noted in my other reply, simple http auth is not practically very > > useful for the kinds of sources we want to access, so if libvirt never > > supported it I wouldn't bother adding that complexity now. > > > As far as I can tell, we haven't ever supported it. But it is possible that > I missed something in my digging, so if anybody has any recollection of http > auth being supported in the past, please chime in. I don't think it was really supported. There were some bits present which made me to think that it was supported in the -drive code, so I've forward ported the functionality to the -blockdev code, but when I actually try it we don't setup the 'secret' object which is supposed to store the password and thus end up crashing in qemuBlockStorageSourceGetCURLProps I'll post patches to address that, but the question is whether we want to bother with actually supporting the password authentication or not, because the simpler approach to fixing the bug is to simply allow it.
Re: Network disks and replacing qemu-block-curl|ssh with nbdkit
On Tue, Apr 19, 2022 at 22:30:51 +0100, Richard W.M. Jones wrote:
> On Tue, Apr 19, 2022 at 03:00:58PM -0500, Jonathon Jongsma wrote:
> > On 4/19/22 12:31 PM, Richard W.M. Jones wrote:
[..]
> > >Now actual support for protocol='ssh' (as in, the main drive, not only
> > >in the backing chain), while not currently documented, seems to be
> > >sort of working. libguestfs will try to create a protocol='ssh' drive
> > >through libvirt if you ask it:
> > >
> > > $ guestfish --format=raw -a ssh://foo/var/tmp/newdisk run
> > > libguestfs: error: could not create appliance through libvirt.
> > > ...
> > > Original error from libvirt: internal error: qemu unexpectedly closed
> > > the monitor: 2022-04-19T17:19:47.096384Z qemu-kvm: -blockdev
> > > {"driver":"ssh","path":"/var/tmp/newdisk","server":{"host":"foo","port":"22"},"node-name":"libvirt-2-storage","cache":{"direct":false,"no-flush":false},"auto-read-only":true,"discard":"unmap"}:
> > > failed to authenticate using publickey authentication and the identities
> > > held by your ssh-agent [code=1 int1=-1]
> > >
> > >If you add -vx to the guestfish command you can see the libvirt XML
> > >fragment that was used:
> > >
> > >
> > >
> > >
> > >
> > >
> > >
> > >
> > >
> > >
> > >which looks plausible. I don't understand why it doesn't work,
> > >because I've got my agent set up correctly. I wonder if it's not
> > >passing SSH_AUTH_SOCK through to session virtqemud?
> > >
> > >Rich.
> >
> > This looks like the same thing:
> > https://bugzilla.redhat.com/show_bug.cgi?id=1140166 (and associated
> > duplicates). It was finally closed deferred last year.
> >
> > Does this mean that the ssh disk source never properly worked in libvirt?
SSH disk sources indeed never worked properly.
The existing infrastructure we have was added for the sole purpose to
allow existing libguestfs images to work. The problem why it never got
implemented was that the socket to the ssh agent was to be passed as an
environment variable to qemu so it made it very unwieldy to actually
implement it properly.
At the time I've re-wrote to use -blockdev it became necessary to be
able to parse the backing image definition at least to some extend and
thus the partial support for 'ssh' protocol was added and the support
for 'slice'-ing of the storage was added (libguestfs was accessing a
disk image inside a tar archive without actually extracting it).
