- Devel - libvirt List Archives

[libvirt] Google Summer of Code 2014 - Rewriting Virtual-Box Driver
by prashanth sunder 11 Mar '14

11 Mar '14

Hello, I am applying for the project idea "Rewriting Virtual-Box Driver" suggested by Michal Privoznik(mprivozn(a)redhat.com) in the "Qemu" ideas page ( http://wiki.qemu.org/Google_Summer_of_Code_2014) In the short span of time that I had after my discussion with Mr. Privoznik, the current Virtual Box driver code is not structured very well(lot of #ifdef's in the current code) and very hard to read. Since libvirt has to support all versions of Virtual Box, the current code decides on what code to compile based on the value of the macro VBOX_API_VERSION that is checked during ./configure. The only thing after discussion that we were able to come up with is putting version specific code under particular files and only compile the those necessary files during "make" For instance, if a function X() supports version A, B, C we will have function X() in vbox_A.c just for version A, function X() in vbox_B.c just for version B and so on. Any other suggestions than the above mentioned one which can be used to fix the problem?? Regards, Prashanth Sunder

2 1

[libvirt] [PATCH] Fix sec label setup when attaching to QEMU processes
by Daniel P. Berrange 11 Mar '14

11 Mar '14

When attaching to a QEMU process, the def->seclabels array is going to be empty. The qemuProcessAttach method must thus populate it with data for the security drivers. Signed-off-by: Daniel P. Berrange <berrange(a)redhat.com> --- src/qemu/qemu_process.c | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/src/qemu/qemu_process.c b/src/qemu/qemu_process.c index 1f00840..7d41c93 100644 --- a/src/qemu/qemu_process.c +++ b/src/qemu/qemu_process.c @@ -4479,6 +4479,7 @@ int qemuProcessAttach(virConnectPtr conn ATTRIBUTE_UNUSED, virDomainPausedReason reason; virSecurityLabelPtr seclabel = NULL; virSecurityLabelDefPtr seclabeldef = NULL; + bool seclabelgen = false; virSecurityManagerPtr* sec_managers = NULL; const char *model; virQEMUDriverConfigPtr cfg = virQEMUDriverGetConfig(driver); @@ -4529,10 +4530,16 @@ int qemuProcessAttach(virConnectPtr conn ATTRIBUTE_UNUSED, goto error; for (i = 0; sec_managers[i]; i++) { + seclabelgen = false; + VIR_ERROR("Iter %zu", i); model = virSecurityManagerGetModel(sec_managers[i]); seclabeldef = virDomainDefGetSecurityLabelDef(vm->def, model); - if (seclabeldef == NULL) - goto error; + VIR_ERROR("model %s def %p", model, seclabeldef); + if (seclabeldef == NULL) { + if (!(seclabeldef = virDomainDefGenSecurityLabelDef(model))) + goto error; + seclabelgen = true; + } seclabeldef->type = VIR_DOMAIN_SECLABEL_STATIC; if (VIR_ALLOC(seclabel) < 0) goto error; @@ -4546,6 +4553,12 @@ int qemuProcessAttach(virConnectPtr conn ATTRIBUTE_UNUSED, if (VIR_STRDUP(seclabeldef->label, seclabel->label) < 0) goto error; VIR_FREE(seclabel); + + if (seclabelgen) { + if (VIR_APPEND_ELEMENT(vm->def->seclabels, vm->def->nseclabels, seclabeldef) < 0) + goto error; + seclabelgen = false; + } } VIR_DEBUG("Creating domain log file"); @@ -4692,6 +4705,8 @@ error: VIR_FORCE_CLOSE(logfile); VIR_FREE(seclabel); VIR_FREE(sec_managers); + if (seclabelgen) + virSecurityLabelDefFree(seclabeldef); virDomainChrSourceDefFree(monConfig); virObjectUnref(cfg); virObjectUnref(caps); -- 1.8.5.3

2 2

[libvirt] Suspending access to opened/active /dev/nodes during application runtime
by Lukasz Pawelczyk 11 Mar '14

11 Mar '14

Problem: Has anyone thought about a mechanism to limit/remove an access to a device during an application runtime? Meaning we have an application that has an open file descriptor to some /dev/node and depending on *something* it gains or looses the access to it gracefully (with or without a notification, but without any fatal consequences). Example: LXC. Imagine we have 2 separate containers. Both running full operating systems. Specifically with 2 X servers. Both running concurrently of course. Both need the same input devices (e.g. we have just one mouse). This creates a security problem when we want to have completely separate environments. One container is active (being displayed on a monitor and controlled with a mouse) while the other container runs evtest /dev/input/something and grabs the secret password user typed in the other. Solutions: The complete solution would comprise of 2 parts: - a mechanism that would allow to temporally "hide" a device from an open file descriptor. - a mechanism for deciding whether application/process/namespace should have an access to a specific device at a specific moment Let's focus on the first problem only, as it would need to be solved first anyway. I haven't found anything that would allow me to do it. There are a lot mechanisms that make it possible to restrict an access during open(): - DAC - ACL (controlled by hand or with uaccess) - LSM (in general) - device cgroups But all of those can't do a thing when the device is already opened and an application has a file descriptor. I don't see such mechanism in kernel sources either. I do imagine that it would not be possible for every device to handle such a thing (dri comes to mind) without breaking something (graphics card state in dri example). But there is class of simple input/output devices that would handle this without problems. I did implement some proof-of-concept solution for an evdev driver by allowing or disallowing events that go to evdev_client structure using some arbitrary condition. But this is far from a generic solution. My proof-of-concept is somewhat similar to this (I just found it): http://www.spinics.net/lists/linux-input/msg25547.html Though a little bit wider in scope. But neither is flawless nor generic. Has anyone had any thoughts about a similar problem? -- Regards Havner

4 5

[libvirt] How to apply for Google Summer of Code
by Stefan Hajnoczi 11 Mar '14

11 Mar '14

Dear students, Applications for Google Summer of Code opened on Monday, 10th of March and will continue until Friday, 21st of March. The common question we are getting is "How do I apply?" :). Here is the application checklist: 1. Choose a project idea and get in touch with the mentor. The project ideas and mentors are listed here: http://qemu-project.org/Google_Summer_of_Code_2014 2. Put together a rough project plan (design + schedule) that breaks down the solution you are proposing. You can email a draft to your mentor for feedback or ask for clarifications about the project idea. 3. Go to http://google-melange.com/, log in and submit your application form for QEMU. The application template is here: https://www.google-melange.com/gsoc/org2/google/gsoc2014/qemu Remember the deadline for applications Friday, 21st of March. You can reach mentors on #qemu-gsoc on irc.oftc.net or via email. Stefan

1 0

[libvirt] [PATCH v2 0/3] Add caching of QEMU probed capabilities
by Daniel P. Berrange 11 Mar '14

11 Mar '14

A followup to https://www.redhat.com/archives/libvir-list/2014-March/msg00297.html Probing capabilities takes 200-300ms per binary and we have as many as 26 binaries. This noticably slows down libvirtd startup. It does not look like performance of probing QEMU can be improved, so this series introduces caching of the capabilities information. So the first time libvirtd starts it'll be slow, but thereafter it is fast. The cache is invalidated any time the QEMU binary timestamp changes or the libvirtd binary or driver module timestamp changes. In v2: - Store timestamps in XML file instead of non-portable utimes() - Use ctime instead of mtime since the latter can be faked by package managers to go backwards in time. Daniel P. Berrange (3): Add helper APIs to track if libvirtd or loadable modules have changed Change QEMU capabilities cache to check ctime instead of mtime Cache result of QEMU capabilities extraction daemon/libvirtd.c | 2 + src/driver.c | 2 + src/libvirt_private.syms | 2 + src/qemu/qemu_capabilities.c | 442 +++++++++++++++++++++++++++++++++++++++++-- src/qemu/qemu_capabilities.h | 2 + src/qemu/qemu_driver.c | 1 + src/util/virutil.c | 23 +++ src/util/virutil.h | 4 + 8 files changed, 467 insertions(+), 11 deletions(-) -- 1.8.5.3

3 8

[libvirt] [PATCH] tests: Distribute securityselinuxhelperdata
by Jiri Denemark 11 Mar '14

11 Mar '14

Signed-off-by: Jiri Denemark <jdenemar(a)redhat.com> --- Notes: Pushed as a build-breaker since 'make distcheck' fails without this patch. tests/Makefile.am | 1 + 1 file changed, 1 insertion(+) diff --git a/tests/Makefile.am b/tests/Makefile.am index 5c1f420..3267ad3 100644 --- a/tests/Makefile.am +++ b/tests/Makefile.am @@ -97,6 +97,7 @@ EXTRA_DIST = \ qemuxml2xmloutdata \ qemuxmlnsdata \ secretxml2xmlin \ + securityselinuxhelperdata \ securityselinuxlabeldata \ schematestutils.sh \ sexpr2xmldata \ -- 1.9.0

1 0

[libvirt] [PATCH] BZ1072677: Avoid freeing of 0 file descriptor
by Stefan Berger 11 Mar '14

11 Mar '14

From: Stefan Berger <stefanb(a)linux.vnet.ibm.com> Avoid the freeing of an array of zero file descriptors in case of error. Introduce a macro VIR_INIT_N_FD to initialize such an array's elements to -1. Signed-off-by: Stefan Berger <stefanb(a)linux.vnet.ibm.com> --- src/qemu/qemu_hotplug.c | 14 +++++++++++--- src/util/virfile.h | 12 ++++++++++++ 2 files changed, 23 insertions(+), 3 deletions(-) diff --git a/src/qemu/qemu_hotplug.c b/src/qemu/qemu_hotplug.c index 6703c92..b295db2 100644 --- a/src/qemu/qemu_hotplug.c +++ b/src/qemu/qemu_hotplug.c @@ -874,9 +874,12 @@ int qemuDomainAttachNetDevice(virConnectPtr conn, tapfdSize = vhostfdSize = net->driver.virtio.queues; if (!tapfdSize) tapfdSize = vhostfdSize = 1; - if (VIR_ALLOC_N(tapfd, tapfdSize) < 0 || - VIR_ALLOC_N(vhostfd, vhostfdSize) < 0) + if (VIR_ALLOC_N(tapfd, tapfdSize) < 0) goto cleanup; + VIR_INIT_N_FD(tapfd, tapfdSize); + if (VIR_ALLOC_N(vhostfd, vhostfdSize) < 0) + goto cleanup; + VIR_INIT_N_FD(vhostfd, vhostfdSize); if (qemuNetworkIfaceConnect(vm->def, conn, driver, net, priv->qemuCaps, tapfd, &tapfdSize) < 0) goto cleanup; @@ -885,8 +888,12 @@ int qemuDomainAttachNetDevice(virConnectPtr conn, goto cleanup; } else if (actualType == VIR_DOMAIN_NET_TYPE_DIRECT) { tapfdSize = vhostfdSize = 1; - if (VIR_ALLOC(tapfd) < 0 || VIR_ALLOC(vhostfd) < 0) + if (VIR_ALLOC(tapfd) < 0) + goto cleanup; + *tapfd = -1; + if (VIR_ALLOC(vhostfd) < 0) goto cleanup; + *vhostfd = -1; if ((tapfd[0] = qemuPhysIfaceConnect(vm->def, driver, net, priv->qemuCaps, VIR_NETDEV_VPORT_PROFILE_OP_CREATE)) < 0) @@ -898,6 +905,7 @@ int qemuDomainAttachNetDevice(virConnectPtr conn, vhostfdSize = 1; if (VIR_ALLOC(vhostfd) < 0) goto cleanup; + *vhostfd = -1; if (qemuOpenVhostNet(vm->def, net, priv->qemuCaps, vhostfd, &vhostfdSize) < 0) goto cleanup; } diff --git a/src/util/virfile.h b/src/util/virfile.h index 20baf6f..802cf01 100644 --- a/src/util/virfile.h +++ b/src/util/virfile.h @@ -75,6 +75,18 @@ FILE *virFileFdopen(int *fdptr, const char *mode) ATTRIBUTE_RETURN_CHECK; VIR_FILE_CLOSE_PRESERVE_ERRNO | \ VIR_FILE_CLOSE_DONT_LOG)) +static inline void vir_init_n_int(int *ptr, int count, int value) +{ + int i; + + for (i = 0; i < count; i++) + ptr[i] = value; +} + +/* Initialize an array of file descriptors to -1 */ +# define VIR_INIT_N_FD(ptr, count) \ + vir_init_n_int(ptr, count, -1) + /* Opaque type for managing a wrapper around a fd. */ struct _virFileWrapperFd; -- 1.8.1.4

3 5

[libvirt] [PATCH v2] qemu: cleanup tap devices on FreeBSD
by Roman Bogorodskiy 11 Mar '14

11 Mar '14

We have to explicitly destroy TAP devices on FreeBSD because they're not freed after being closed, otherwise we end up with orphaned TAP devices after destroying a domain. --- src/qemu/qemu_process.c | 7 +++++++ src/util/virnetdevtap.h | 6 ++++++ 2 files changed, 13 insertions(+) diff --git a/src/qemu/qemu_process.c b/src/qemu/qemu_process.c index ffa939a..6806539 100644 --- a/src/qemu/qemu_process.c +++ b/src/qemu/qemu_process.c @@ -61,6 +61,7 @@ #include "viruuid.h" #include "virprocess.h" #include "virtime.h" +#include "virnetdevbridge.h" #include "virnetdevtap.h" #include "virbitmap.h" #include "viratomic.h" @@ -4381,6 +4382,12 @@ void qemuProcessStop(virQEMUDriverPtr driver, virDomainNetGetActualVirtPortProfile(net), cfg->stateDir)); VIR_FREE(net->ifname); +#ifdef VIR_NETDEV_TAP_REQUIRE_MANUAL_CLEANUP + } else if (virDomainNetGetActualType(net) == VIR_DOMAIN_NET_TYPE_BRIDGE) { + ignore_value(virNetDevBridgeRemovePort(virDomainNetGetActualBridgeName(net), + net->ifname)); + ignore_value(virNetDevTapDelete(net->ifname)); +#endif } /* release the physical device (or any other resources used by * this interface in the network driver diff --git a/src/util/virnetdevtap.h b/src/util/virnetdevtap.h index a762b31..1e5bd19 100644 --- a/src/util/virnetdevtap.h +++ b/src/util/virnetdevtap.h @@ -27,6 +27,12 @@ # include "virnetdevvportprofile.h" # include "virnetdevvlan.h" +# ifdef __FreeBSD__ +/* This should be defined on OSes that don't automatically + * cleanup released devices */ +# define VIR_NETDEV_TAP_REQUIRE_MANUAL_CLEANUP 1 +# endif + int virNetDevTapCreate(char **ifname, int *tapfd, int tapfdSize, -- 1.8.4.3

2 2

[libvirt] [PATCH] datatypes: Fix comments
by Michael Chapman 11 Mar '14

11 Mar '14

- As of commit 2ff4c137, all virGet*() functions in datatypes.c always return pointers to new objects. Objects are not cached in a per-connection hashtable. - Fix variable names in comments for all vir*Dispose() functions in datatypes.c. - Add comments for virGetStream(), virStreamDispose(), virGetDomainSnapshot(), virDomainSnapshotDispose(). Signed-off-by: Michael Chapman <mike(a)very.puzzling.org> --- src/datatypes.c | 126 +++++++++++++++++++++++++++++++++----------------------- 1 file changed, 74 insertions(+), 52 deletions(-) diff --git a/src/datatypes.c b/src/datatypes.c index 20752cd..6f98aed 100644 --- a/src/datatypes.c +++ b/src/datatypes.c @@ -96,9 +96,9 @@ VIR_ONCE_GLOBAL_INIT(virDataTypes) /** * virGetConnect: * - * Allocates a new hypervisor connection structure + * Allocates a new hypervisor connection object. * - * Returns a new pointer or NULL in case of error. + * Returns a pointer to the connection object, or NULL on error. */ virConnectPtr virGetConnect(void) @@ -126,7 +126,7 @@ error: /** * virConnectDispose: - * @conn: the hypervisor connection to release + * @obj: the hypervisor connection to release * * Unconditionally release all memory associated with a connection. * The connection object must not be used once this method returns. @@ -196,12 +196,10 @@ virConnectCloseCallbackDataDispose(void *obj) * @name: pointer to the domain name * @uuid: pointer to the uuid * - * Lookup if the domain is already registered for that connection, - * if yes return a new pointer to it, if no allocate a new structure, - * and register it in the table. In any case a corresponding call to - * virObjectUnref() is needed to not leak data. + * Allocates a new domain object. When the object is no longer needed, + * virObjectUnref() must be called in order to not leak data. * - * Returns a pointer to the domain, or NULL in case of failure + * Returns a pointer to the domain object, or NULL on error. */ virDomainPtr virGetDomain(virConnectPtr conn, const char *name, const unsigned char *uuid) @@ -234,7 +232,7 @@ error: /** * virDomainDispose: - * @domain: the domain to release + * @obj: the domain to release * * Unconditionally release all memory associated with a domain. * The domain object must not be used once this method returns. @@ -262,12 +260,10 @@ virDomainDispose(void *obj) * @name: pointer to the network name * @uuid: pointer to the uuid * - * Lookup if the network is already registered for that connection, - * if yes return a new pointer to it, if no allocate a new structure, - * and register it in the table. In any case a corresponding call to - * virObjectUnref() is needed to not leak data. + * Allocates a new network object. When the object is no longer needed, + * virObjectUnref() must be called in order to not leak data. * - * Returns a pointer to the network, or NULL in case of failure + * Returns a pointer to the network object, or NULL on error. */ virNetworkPtr virGetNetwork(virConnectPtr conn, const char *name, const unsigned char *uuid) @@ -299,7 +295,7 @@ error: /** * virNetworkDispose: - * @network: the network to release + * @obj: the network to release * * Unconditionally release all memory associated with a network. * The network object must not be used once this method returns. @@ -327,13 +323,10 @@ virNetworkDispose(void *obj) * @name: pointer to the interface name * @mac: pointer to the mac * - * Lookup if the interface is already registered for that connection, - * if yes return a new pointer to it (possibly updating the MAC - * address), if no allocate a new structure, and register it in the - * table. In any case a corresponding call to virObjectUnref() is - * needed to not leak data. + * Allocates a new interface object. When the object is no longer needed, + * virObjectUnref() must be called in order to not leak data. * - * Returns a pointer to the interface, or NULL in case of failure + * Returns a pointer to the interface object, or NULL on error. */ virInterfacePtr virGetInterface(virConnectPtr conn, const char *name, const char *mac) @@ -368,7 +361,7 @@ error: /** * virInterfaceDispose: - * @interface: the interface to release + * @obj: the interface to release * * Unconditionally release all memory associated with an interface. * The interface object must not be used once this method returns. @@ -396,12 +389,10 @@ virInterfaceDispose(void *obj) * @privateData: pointer to driver specific private data * @freeFunc: private data cleanup function pointer specfic to driver * - * Lookup if the storage pool is already registered for that connection, - * if yes return a new pointer to it, if no allocate a new structure, - * and register it in the table. In any case a corresponding call to - * virObjectUnref() is needed to not leak data. + * Allocates a new storage pool object. When the object is no longer needed, + * virObjectUnref() must be called in order to not leak data. * - * Returns a pointer to the storage pool, or NULL in case of failure + * Returns a pointer to the storage pool object, or NULL on error. */ virStoragePoolPtr virGetStoragePool(virConnectPtr conn, const char *name, @@ -440,7 +431,7 @@ error: /** * virStoragePoolDispose: - * @pool: the pool to release + * @obj: the storage pool to release * * Unconditionally release all memory associated with a pool. * The pool object must not be used once this method returns. @@ -475,12 +466,10 @@ virStoragePoolDispose(void *obj) * @privateData: pointer to driver specific private data * @freeFunc: private data cleanup function pointer specfic to driver * - * Lookup if the storage vol is already registered for that connection, - * if yes return a new pointer to it, if no allocate a new structure, - * and register it in the table. In any case a corresponding call to - * virObjectUnref() is needed to not leak data. + * Allocates a new storage volume object. When the object is no longer needed, + * virObjectUnref() must be called in order to not leak data. * - * Returns a pointer to the storage vol, or NULL in case of failure + * Returns a pointer to the storage volume object, or NULL on error. */ virStorageVolPtr virGetStorageVol(virConnectPtr conn, const char *pool, const char *name, @@ -520,7 +509,7 @@ error: /** * virStorageVolDispose: - * @vol: the vol to release + * @obj: the storage volume to release * * Unconditionally release all memory associated with a volume. * The volume object must not be used once this method returns. @@ -550,12 +539,10 @@ virStorageVolDispose(void *obj) * @conn: the hypervisor connection * @name: device name (unique on node) * - * Lookup if the device is already registered for that connection, - * if yes return a new pointer to it, if no allocate a new structure, - * and register it in the table. In any case a corresponding call to - * virObjectUnref() is needed to not leak data. + * Allocates a new node device object. When the object is no longer needed, + * virObjectUnref() must be called in order to not leak data. * - * Returns a pointer to the node device, or NULL in case of failure + * Returns a pointer to the node device object, or NULL on error. */ virNodeDevicePtr virGetNodeDevice(virConnectPtr conn, const char *name) @@ -585,7 +572,7 @@ error: /** * virNodeDeviceDispose: - * @dev: the dev to release + * @obj: the node device to release * * Unconditionally release all memory associated with a device. * The device object must not be used once this method returns. @@ -611,12 +598,10 @@ virNodeDeviceDispose(void *obj) * @conn: the hypervisor connection * @uuid: secret UUID * - * Lookup if the secret is already registered for that connection, if so return - * a pointer to it, otherwise allocate a new structure, and register it in the - * table. In any case a corresponding call to virObjectUnref() is needed to not - * leak data. + * Allocates a new secret object. When the object is no longer needed, + * virObjectUnref() must be called in order to not leak data. * - * Returns a pointer to the secret, or NULL in case of failure + * Returns a pointer to the secret object, or NULL on error. */ virSecretPtr virGetSecret(virConnectPtr conn, const unsigned char *uuid, @@ -650,7 +635,7 @@ error: /** * virSecretDispose: - * @secret: the secret to release + * @obj: the secret to release * * Unconditionally release all memory associated with a secret. * The secret object must not be used once this method returns. @@ -672,6 +657,15 @@ virSecretDispose(void *obj) } +/** + * virGetStream: + * @conn: the hypervisor connection + * + * Allocates a new stream object. When the object is no longer needed, + * virObjectUnref() must be called in order to not leak data. + * + * Returns a pointer to the stream object, or NULL on error. + */ virStreamPtr virGetStream(virConnectPtr conn) { @@ -688,6 +682,16 @@ virGetStream(virConnectPtr conn) return ret; } +/** + * virStreamDispose: + * @obj: the stream to release + * + * Unconditionally release all memory associated with a stream. + * The stream object must not be used once this method returns. + * + * It will also unreference the associated connection object, + * which may also be released if its ref count hits zero. + */ static void virStreamDispose(void *obj) { @@ -704,12 +708,10 @@ virStreamDispose(void *obj) * @name: pointer to the network filter pool name * @uuid: pointer to the uuid * - * Lookup if the network filter is already registered for that connection, - * if yes return a new pointer to it, if no allocate a new structure, - * and register it in the table. In any case a corresponding call to - * virObjectUnref() is needed to not leak data. + * Allocates a new network filter object. When the object is no longer needed, + * virObjectUnref() must be called in order to not leak data. * - * Returns a pointer to the network, or NULL in case of failure + * Returns a pointer to the network filter object, or NULL on error. */ virNWFilterPtr virGetNWFilter(virConnectPtr conn, const char *name, @@ -744,7 +746,7 @@ error: /** * virNWFilterDispose: - * @nwfilter: the nwfilter to release + * @obj: the network filter to release * * Unconditionally release all memory associated with a nwfilter. * The nwfilter object must not be used once this method returns. @@ -766,6 +768,16 @@ virNWFilterDispose(void *obj) } +/** + * virGetDomainSnapshot: + * @domain: the domain to snapshot + * @name: pointer to the domain snapshot name + * + * Allocates a new domain snapshot object. When the object is no longer needed, + * virObjectUnref() must be called in order to not leak data. + * + * Returns a pointer to the domain snapshot object, or NULL on error. + */ virDomainSnapshotPtr virGetDomainSnapshot(virDomainPtr domain, const char *name) { @@ -792,6 +804,16 @@ error: } +/** + * virDomainSnapshotDispose: + * @obj: the domain snapshot to release + * + * Unconditionally release all memory associated with a snapshot. + * The snapshot object must not be used once this method returns. + * + * It will also unreference the associated connection object, + * which may also be released if its ref count hits zero. + */ static void virDomainSnapshotDispose(void *obj) { -- 1.8.5.3

1 0

[libvirt] [PATCH] datatypes: Fix comments
by Michael Chapman 11 Mar '14

11 Mar '14

- As of commit 2ff4c137, all virGet*() functions in datatypes.c always return pointers to new objects. Objects are not cached in a per-connection hashtable. - As of commit 46ec5f85, the conn.lock mutex does not need to be held when calling any vir*Dispose() function in datatypes.c (via virObjectUnref()). - Add comments for virGetStream(), virStreamDispose(), virGetDomainSnapshot(), virDomainSnapshotDispose(). Signed-off-by: Michael Chapman <mike(a)very.puzzling.org> --- src/datatypes.c | 174 ++++++++++++++++++++++++++++++++------------------------ 1 file changed, 99 insertions(+), 75 deletions(-) diff --git a/src/datatypes.c b/src/datatypes.c index 73f17e7..aafa54b 100644 --- a/src/datatypes.c +++ b/src/datatypes.c @@ -96,9 +96,8 @@ VIR_ONCE_GLOBAL_INIT(virDataTypes) /** * virGetConnect: * - * Allocates a new hypervisor connection structure - * - * Returns a new pointer or NULL in case of error. + * Allocates and returns a pointer to a new hypervisor connection object. + * Returns NULL on error. */ virConnectPtr virGetConnect(void) @@ -129,9 +128,7 @@ error: * @conn: the hypervisor connection to release * * Unconditionally release all memory associated with a connection. - * The conn.lock mutex must be held prior to calling this, and will - * be released prior to this returning. The connection obj must not - * be used once this method returns. + * The connection object must not be used once this method returns. */ static void virConnectDispose(void *obj) @@ -198,12 +195,12 @@ virConnectCloseCallbackDataDispose(void *obj) * @name: pointer to the domain name * @uuid: pointer to the uuid * - * Lookup if the domain is already registered for that connection, - * if yes return a new pointer to it, if no allocate a new structure, - * and register it in the table. In any case a corresponding call to - * virObjectUnref() is needed to not leak data. + * Allocates and returns a pointer to a new domain object. + * Returns NULL on error. * - * Returns a pointer to the domain, or NULL in case of failure + * The domain object holds a reference to the hypervisor connection. + * When the domain object is no longer needed, virObjectUnref() must be + * called in order to not leak data. */ virDomainPtr virGetDomain(virConnectPtr conn, const char *name, const unsigned char *uuid) @@ -239,9 +236,7 @@ error: * @domain: the domain to release * * Unconditionally release all memory associated with a domain. - * The conn.lock mutex must be held prior to calling this, and will - * be released prior to this returning. The domain obj must not - * be used once this method returns. + * The domain object must not be used once this method returns. * * It will also unreference the associated connection object, * which may also be released if its ref count hits zero. @@ -266,12 +261,12 @@ virDomainDispose(void *obj) * @name: pointer to the network name * @uuid: pointer to the uuid * - * Lookup if the network is already registered for that connection, - * if yes return a new pointer to it, if no allocate a new structure, - * and register it in the table. In any case a corresponding call to - * virObjectUnref() is needed to not leak data. + * Allocates and returns a pointer to a new network object. + * Returns NULL on error. * - * Returns a pointer to the network, or NULL in case of failure + * The network object holds a reference to the hypervisor connection. + * When the network object is no longer needed, virObjectUnref() must be + * called in order to not leak data. */ virNetworkPtr virGetNetwork(virConnectPtr conn, const char *name, const unsigned char *uuid) @@ -306,9 +301,7 @@ error: * @network: the network to release * * Unconditionally release all memory associated with a network. - * The conn.lock mutex must be held prior to calling this, and will - * be released prior to this returning. The network obj must not - * be used once this method returns. + * The network object must not be used once this method returns. * * It will also unreference the associated connection object, * which may also be released if its ref count hits zero. @@ -333,13 +326,12 @@ virNetworkDispose(void *obj) * @name: pointer to the interface name * @mac: pointer to the mac * - * Lookup if the interface is already registered for that connection, - * if yes return a new pointer to it (possibly updating the MAC - * address), if no allocate a new structure, and register it in the - * table. In any case a corresponding call to virObjectUnref() is - * needed to not leak data. + * Allocates and returns a pointer to a new interface object. + * Returns NULL on error. * - * Returns a pointer to the interface, or NULL in case of failure + * The interface object holds a reference to the hypervisor connection. + * When the interface object is no longer needed, virObjectUnref() must be + * called in order to not leak data. */ virInterfacePtr virGetInterface(virConnectPtr conn, const char *name, const char *mac) @@ -377,9 +369,7 @@ error: * @interface: the interface to release * * Unconditionally release all memory associated with an interface. - * The conn.lock mutex must be held prior to calling this, and will - * be released prior to this returning. The interface obj must not - * be used once this method returns. + * The interface object must not be used once this method returns. * * It will also unreference the associated connection object, * which may also be released if its ref count hits zero. @@ -404,12 +394,12 @@ virInterfaceDispose(void *obj) * @privateData: pointer to driver specific private data * @freeFunc: private data cleanup function pointer specfic to driver * - * Lookup if the storage pool is already registered for that connection, - * if yes return a new pointer to it, if no allocate a new structure, - * and register it in the table. In any case a corresponding call to - * virObjectUnref() is needed to not leak data. + * Allocates and returns a pointer to a new storage pool object. + * Returns NULL on error. * - * Returns a pointer to the storage pool, or NULL in case of failure + * The pool object holds a reference to the hypervisor connection. + * When the pool object is no longer needed, virObjectUnref() must be + * called in order to not leak data. */ virStoragePoolPtr virGetStoragePool(virConnectPtr conn, const char *name, @@ -451,9 +441,7 @@ error: * @pool: the pool to release * * Unconditionally release all memory associated with a pool. - * The conn.lock mutex must be held prior to calling this, and will - * be released prior to this returning. The pool obj must not - * be used once this method returns. + * The pool object must not be used once this method returns. * * It will also unreference the associated connection object, * which may also be released if its ref count hits zero. @@ -485,12 +473,12 @@ virStoragePoolDispose(void *obj) * @privateData: pointer to driver specific private data * @freeFunc: private data cleanup function pointer specfic to driver * - * Lookup if the storage vol is already registered for that connection, - * if yes return a new pointer to it, if no allocate a new structure, - * and register it in the table. In any case a corresponding call to - * virObjectUnref() is needed to not leak data. + * Allocates and returns a pointer to a new storage volume object. + * Returns NULL on error. * - * Returns a pointer to the storage vol, or NULL in case of failure + * The volume object holds a reference to the hypervisor connection. + * When the volume object is no longer needed, virObjectUnref() must be + * called in order to not leak data. */ virStorageVolPtr virGetStorageVol(virConnectPtr conn, const char *pool, const char *name, @@ -532,10 +520,8 @@ error: * virStorageVolDispose: * @vol: the vol to release * - * Unconditionally release all memory associated with a vol. - * The conn.lock mutex must be held prior to calling this, and will - * be released prior to this returning. The vol obj must not - * be used once this method returns. + * Unconditionally release all memory associated with a volume. + * The volume object must not be used once this method returns. * * It will also unreference the associated connection object, * which may also be released if its ref count hits zero. @@ -562,12 +548,12 @@ virStorageVolDispose(void *obj) * @conn: the hypervisor connection * @name: device name (unique on node) * - * Lookup if the device is already registered for that connection, - * if yes return a new pointer to it, if no allocate a new structure, - * and register it in the table. In any case a corresponding call to - * virObjectUnref() is needed to not leak data. + * Allocates and returns a pointer to a new node device object. + * Returns NULL on error. * - * Returns a pointer to the node device, or NULL in case of failure + * The device object holds a reference to the hypervisor connection. + * When the device object is no longer needed, virObjectUnref() must be + * called in order to not leak data. */ virNodeDevicePtr virGetNodeDevice(virConnectPtr conn, const char *name) @@ -599,10 +585,8 @@ error: * virNodeDeviceDispose: * @dev: the dev to release * - * Unconditionally release all memory associated with a dev. - * The conn.lock mutex must be held prior to calling this, and will - * be released prior to this returning. The dev obj must not - * be used once this method returns. + * Unconditionally release all memory associated with a device. + * The device object must not be used once this method returns. * * It will also unreference the associated connection object, * which may also be released if its ref count hits zero. @@ -625,12 +609,12 @@ virNodeDeviceDispose(void *obj) * @conn: the hypervisor connection * @uuid: secret UUID * - * Lookup if the secret is already registered for that connection, if so return - * a pointer to it, otherwise allocate a new structure, and register it in the - * table. In any case a corresponding call to virObjectUnref() is needed to not - * leak data. + * Allocates and returns a pointer to a new secret object. + * Returns NULL on error. * - * Returns a pointer to the secret, or NULL in case of failure + * The secret object holds a reference to the hypervisor connection. + * When the secret object is no longer needed, virObjectUnref() must be + * called in order to not leak data. */ virSecretPtr virGetSecret(virConnectPtr conn, const unsigned char *uuid, @@ -666,12 +650,11 @@ error: * virSecretDispose: * @secret: the secret to release * - * Unconditionally release all memory associated with a secret. The conn.lock - * mutex must be held prior to calling this, and will be released prior to this - * returning. The secret obj must not be used once this method returns. + * Unconditionally release all memory associated with a secret. + * The secret object must not be used once this method returns. * - * It will also unreference the associated connection object, which may also be - * released if its ref count hits zero. + * It will also unreference the associated connection object, + * which may also be released if its ref count hits zero. */ static void virSecretDispose(void *obj) @@ -687,6 +670,17 @@ virSecretDispose(void *obj) } +/** + * virGetStream: + * @conn: the hypervisor connection + * + * Allocates and returns a pointer to a new stream object. + * Returns NULL on error. + * + * The secret object holds a reference to the hypervisor connection. + * When the secret object is no longer needed, virObjectUnref() must be + * called in order to not leak data. + */ virStreamPtr virGetStream(virConnectPtr conn) { @@ -703,6 +697,16 @@ virGetStream(virConnectPtr conn) return ret; } +/** + * virStreamDispose: + * @stream: the stream to release + * + * Unconditionally release all memory associated with a stream. + * The stream object must not be used once this method returns. + * + * It will also unreference the associated connection object, + * which may also be released if its ref count hits zero. + */ static void virStreamDispose(void *obj) { @@ -719,12 +723,12 @@ virStreamDispose(void *obj) * @name: pointer to the network filter pool name * @uuid: pointer to the uuid * - * Lookup if the network filter is already registered for that connection, - * if yes return a new pointer to it, if no allocate a new structure, - * and register it in the table. In any case a corresponding call to - * virObjectUnref() is needed to not leak data. + * Allocates and returns a pointer to a new nwfilter object. + * Returns NULL on error. * - * Returns a pointer to the network, or NULL in case of failure + * The nwfilter object holds a reference to the hypervisor connection. + * When the nwfilter object is no longer needed, virObjectUnref() must be + * called in order to not leak data. */ virNWFilterPtr virGetNWFilter(virConnectPtr conn, const char *name, @@ -762,9 +766,7 @@ error: * @nwfilter: the nwfilter to release * * Unconditionally release all memory associated with a nwfilter. - * The conn.lock mutex must be held prior to calling this, and will - * be released prior to this returning. The nwfilter obj must not - * be used once this method returns. + * The nwfilter object must not be used once this method returns. * * It will also unreference the associated connection object, * which may also be released if its ref count hits zero. @@ -783,6 +785,18 @@ virNWFilterDispose(void *obj) } +/** + * virGetDomainSnapshot: + * @conn: the hypervisor connection + * @name: pointer to the domain snapshot name + * + * Allocates and returns a pointer to a new domain snapshot object. + * Returns NULL on error. + * + * The snapshot object holds a reference to the hypervisor connection. + * When the snapshot object is no longer needed, virObjectUnref() must be + * called in order to not leak data. + */ virDomainSnapshotPtr virGetDomainSnapshot(virDomainPtr domain, const char *name) { @@ -809,6 +823,16 @@ error: } +/** + * virDomainSnapshotDispose: + * @snapshot: the snapshot to release + * + * Unconditionally release all memory associated with a snapshot. + * The snapshot object must not be used once this method returns. + * + * It will also unreference the associated connection object, + * which may also be released if its ref count hits zero. + */ static void virDomainSnapshotDispose(void *obj) { -- 1.8.5.3

2 3