Commit Graph

98 Commits

Author SHA1 Message Date
Daniel P. Berrange
64702ac367 Fix handling of whitespae in preprocessor macros for API generator
The apibuild.py script did not handle whitespace in preprocessor
macros, so it failed to detect constants declared with '# define'
instead of '#define'. Since we now correctly indent our public
header files, we have silently lost all constants from
libvirt-api.xml. This also caused us to not detect formatting
errors in constant docs
2014-12-04 15:00:30 +00:00
Daniel P. Berrange
47fb613873 Fix API docs for header file re-organization
The API docs generators were broken by the header file
re-organization. Specifically

 * html/libvirt-libvirt.html was empty (and should be deleted)
 * Makefile.am didn't install html/libvirt-libvirt-*.html
 * hvsupport.html was mostly empty
 * sitemap.html.in didn't list the new html/*.html files
2014-11-13 10:20:26 +00:00
Daniel P. Berrange
bcec07b9f0 Move virConnect related APIs out of libvirt.h.in
Create a new libvirt-host.h file to hold the public
API definitions for the virConnect type. This header
file is not self-contained, so applications will not directly
include it. They will continue to #include <libvirt/libvirt.h>
2014-10-24 17:23:51 +01:00
Daniel P. Berrange
653a5e4939 Move virDomain related APIs out of libvirt.h.in
Create a new libvirt-domain.h file to hold the public
API definitions for the virDomain type. This header
file is not self-contained, so applications will not directly
include it. They will continue to #include <libvirt/libvirt.h>
2014-10-24 17:23:32 +01:00
Daniel P. Berrange
6d9c5f3735 Move virEvent related APIs out of libvirt.h.in
Create a new libvirt-event.h file to hold the public
API definitions for the virEvent type. This header
file is not self-contained, so applications will not directly
include it. They will continue to #include <libvirt/libvirt.h>
2014-10-24 17:23:17 +01:00
Daniel P. Berrange
c9456e1a7f Move virStoragePool/Vol related APIs out of libvirt.h.in
Create a new libvirt-storage.h file to hold the public
API definitions for the virStorage/Vol type. This header
file is not self-contained, so applications will not directly
include it. They will continue to #include <libvirt/libvirt.h>
2014-10-24 17:22:57 +01:00
Daniel P. Berrange
2805ddb29a Move virStream related APIs out of libvirt.h.in
Create a new libvirt-stream.h file to hold the public
API definitions for the virStream type. This header
file is not self-contained, so applications will not directly
include it. They will continue to #include <libvirt/libvirt.h>

Note the definition of virStreamPtr is not moved, since that
must be declared early for all other libvirt APIs to be able
to reference it.
2014-10-24 17:22:38 +01:00
Daniel P. Berrange
75ff42fe7c Move virSecret related APIs out of libvirt.h.in
Create a new libvirt-secret.h file to hold the public
API definitions for the virSecret type. This header
file is not self-contained, so applications will not directly
include it. They will continue to #include <libvirt/libvirt.h>
2014-10-24 17:22:20 +01:00
Daniel P. Berrange
0147d6b88f Move virNodeDevice related APIs out of libvirt.h.in
Create a new libvirt-nodedev.h file to hold the public
API definitions for the virNodeDevice type. This header
file is not self-contained, so applications will not directly
include it. They will continue to #include <libvirt/libvirt.h>
2014-10-24 17:21:59 +01:00
Daniel P. Berrange
40741984fc Move virNWFilter related APIs out of libvirt.h.in
Create a new libvirt-nwfilter.h file to hold the public
API definitions for the virNWFilter type. This header
file is not self-contained, so applications will not directly
include it. They will continue to #include <libvirt/libvirt.h>
2014-10-24 17:21:34 +01:00
Daniel P. Berrange
fc964bfc27 Move virInterface related APIs out of libvirt.h.in
Create a new libvirt-interface.h file to hold the public
API definitions for the virInterface type. This header
file is not self-contained, so applications will not directly
include it. They will continue to #include <libvirt/libvirt.h>
2014-10-24 17:21:15 +01:00
Daniel P. Berrange
5c9789d2d1 Move virNetwork related APIs out of libvirt.h.in
Create a new libvirt-network.h file to hold the public
API definitions for the virNetwork type. This header
file is not self-contained, so applications will not directly
include it. They will continue to #include <libvirt/libvirt.h>
2014-10-24 17:20:52 +01:00
Daniel P. Berrange
84783d9d1c Move virDomainSnapshot related APIs out of libvirt.h.in
Create a new libvirt-domain-snapshot.h file to hold the public
API definitions for the virDomainSnapshot type. This header
file is not self-contained, so applications will not directly
include it. They will continue to #include <libvirt/libvirt.h>
2014-10-24 17:20:20 +01:00
Daniel P. Berrange
0399b188ac Move virConnect/virNode related APIs out of libvirt.c
Introduce a src/libvirt-host.c file to hold all the
methods related to the virConnect type.
2014-10-24 16:59:58 +01:00
Daniel P. Berrange
67c08fccdc Move virDomain related APIs out of libvirt.c
Introduce a src/libvirt-domain.c file to hold all the
methods related to the virDomain type.
2014-10-24 16:59:56 +01:00
Daniel P. Berrange
8444015446 Make virTypedParameterValidateSet non-static
The virTypedParameterValidateSet method will need to be used
from several libvirt-*.c files so must be non-static

Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2014-10-24 16:54:48 +01:00
Daniel P. Berrange
36b5d006c1 Move virStorage{Pool,Vol} related APIs out of libvirt.c
Introduce a src/libvirt-storage.c file to hold all the
methods related to the virStorage{Pool,Vol} types.
2014-10-24 16:49:10 +01:00
Daniel P. Berrange
0c94d78bb5 Move virStream related APIs out of libvirt.c
Introduce a src/libvirt-stream.c file to hold all the
methods related to the virStream type.
2014-10-24 16:42:49 +01:00
Daniel P. Berrange
d83ccd6e61 Move virSecret related APIs out of libvirt.c
Introduce a src/libvirt-secret.c file to hold all the
methods related to the virSecret type.
2014-10-24 16:39:05 +01:00
Daniel P. Berrange
e33ed8cdfe Move virNodeDevice related APIs out of libvirt.c
Introduce a src/libvirt-nodedev.c file to hold all the
methods related to the virNodeDevice type.
2014-10-24 16:26:55 +01:00
Daniel P. Berrange
35ed98755f Move virNWFilter related APIs out of libvirt.c
Introduce a src/libvirt-nwfilter.c file to hold all the
methods related to the virNWFilter type.
2014-10-24 16:15:46 +01:00
Daniel P. Berrange
6e01ef230b Move virInterface related APIs out of libvirt.c
Introduce a src/libvirt-interface.c file to hold all the
methods related to the virInterface type.
2014-10-24 16:08:28 +01:00
Daniel P. Berrange
4e00b6bc6a Move virNetwork related APIs out of libvirt.c
Introduce a src/libvirt-network.c file to hold all the
methods related to the virNetwork type.
2014-10-24 16:00:21 +01:00
Daniel P. Berrange
62cf32d0c9 Move virDomainSnapshot related APIs out of libvirt.c
Introduce a src/libvirt-domain-snapshot.c file to hold all the
methods related to the virDomainSnapshot type.
2014-10-24 15:59:22 +01:00
Eric Blake
9b291bbe20 docs: publish correct enum values
We publish libvirt-api.xml for others to use, and in fact, the
libvirt-python bindings use it to generate python constants that
correspond to our enum values.  However, we had an off-by-one bug
that any enum that relied on C's rules for implicit initialization
of the first enum member to 0 got listed in the xml as having a
value of 1 (and all later members of the enum were equally
botched).

The fix is simple - since we add one to the previous value when
encountering an enum without an initializer, the previous value
must start at -1 so that the first enum member is assigned 0.

The python generator code has had the off-by-one ever since DV
first wrote it years ago, but most of our public enums were immune
because they had an explicit = 0 initializer.  The only affected
enums are:
- virDomainEventGraphicsAddressType (such as
VIR_DOMAIN_EVENT_GRAPHICS_ADDRESS_IPV4), since commit 987e31e
(libvirt v0.8.0)
- virDomainCoreDumpFormat (such as VIR_DOMAIN_CORE_DUMP_FORMAT_RAW),
since commit 9fbaff0 (libvirt v1.2.3)
- virIPAddrType (such as VIR_IP_ADDR_TYPE_IPV4), since commit
03e0e79 (not yet released)

Thanks to Nehal J Wani for reporting the problem on IRC, and
for helping me zero in on the culprit function.

* docs/apibuild.py (CParser.parseEnumBlock): Fix implicit enum
values.

Signed-off-by: Eric Blake <eblake@redhat.com>
2014-06-26 15:25:05 -06:00
Michal Privoznik
0f1a0fff0e apibuild: Disallow 'returns' return description
Our documentation generator is a bit messy, to say the least. For
instance, the description to return values of a function is
searched within C comment. Currently, all lines that start with
'returns' or 'Returns' are viewed as return value description.
However, there are some valid uses where the 'returns' word is in
the middle of a sentence describing function behavior not the
return value. And there are no places where 'returns' is used to
describe return values.  For instance:
virDomainDetachDeviceFlags, virConnectNetworkEventRegisterAny and
virDomainGetDiskErrors. This leads to HTML documemtation being
generated incorrectly.

Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
2014-05-13 08:51:11 +02:00
Daniel P. Berrange
2835c1e730 Add virLogSource variables to all source files
Any source file which calls the logging APIs now needs
to have a VIR_LOG_INIT("source.name") declaration at
the start of the file. This provides a static variable
of the virLogSource type.

Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2014-03-18 14:29:22 +00:00
Claudio Bley
2a40951148 Test for object identity when checking for None in Python
Consistently use "is" or "is not" to compare variables to None,
because doing so is preferrable, as per PEP 8
(http://www.python.org/dev/peps/pep-0008/#programming-recommendations):

> Comparisons to singletons like None should always be done with is or
> is not, never the equality operators.
2013-08-23 08:12:26 +02:00
Yuri Chornoivan
5b4c035b08 Fix minor typos in messages and docs
Signed-off-by: Eric Blake <eblake@redhat.com>
2013-07-30 07:07:33 -06:00
Jiri Denemark
c0762b6518 New internal migration APIs with extensible parameters
This patch implements extensible variants of all internal migration APIs
used for v3 migration.
2013-06-25 01:13:16 +02:00
Jiri Denemark
d0d5acb511 Introduce virTypedParamsCopy internal API 2013-06-25 00:38:25 +02:00
Jiri Denemark
fefb0d5464 Introduce VIR_TYPED_PARAMS_DEBUG macro for dumping typed params
All APIs that take typed parameters are only using params address in
their entry point debug messages. With the new VIR_TYPED_PARAMS_DEBUG
macro, all functions can easily log all individual typed parameters
passed to them.
2013-06-25 00:38:24 +02:00
Jiri Denemark
637a7c865a Introduce virTypedParamsCheck internal API
This API is useful for checking whether only a specific subset of
supported typed parameters were passed.
2013-06-25 00:38:24 +02:00
Jiri Denemark
c40ed4168a Rename virTypedParameterArrayValidate as virTypedParamsValidate 2013-06-25 00:38:24 +02:00
Daniel P. Berrange
abe038cfc0 Extend previous check to validate driver struct field names
Ensure that the driver struct field names match the public
API names. For an API virXXXX we must have a driver struct
field xXXXX. ie strip the leading 'vir' and lowercase any
leading uppercase letters.

Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2013-04-24 10:59:53 +01:00
Guido Günther
3591f79b7e Remove more trailing semicolons in Python files 2013-02-07 19:52:44 +01:00
Eric Blake
b2aa03b3f7 docs: don't ignore virEvent API
Commit 6094ad7b (0.9.3 release) promoted several functions from
internal to public, but forgot to fix the documentation generator
to provide details about those functions.

For an example of what this fixes, look at:
file:///path/to/libvirt/docs/html/libvirt-libvirt.html#virEventAddHandle
before and after the patch.

* docs/apibuild.py (ignored_functions): Don't ignore functions
that were turned into official API.
* src/util/virevent.c: Fix comments to pass through parser.
2013-02-01 16:01:45 -07:00
Claudio Bley
7d3cef8a5c docs: abort when missing return or argument documentation
When a function has no associated information to one of its
arguments or its return type we report it and stop with an error.
2013-02-01 08:47:04 +01:00
Claudio Bley
9170ba151d apibuild.py: fix TypeError raised in except clause
When an exception happened inside the try clause in serialize_function,
a new exception was raised in the except clause subsequently:

Traceback (most recent call last):
  File "./apibuild.py", line 2529, in <module>
    rebuild("libvirt")
  File "./apibuild.py", line 2513, in rebuild
    builder.serialize()
  File "./apibuild.py", line 2467, in serialize
    self.serialize_function(output, function)
  File "./apibuild.py", line 2208, in serialize_function
    self.warning("Failed to save function %s info: " % name, `id.info`)
TypeError: warning() takes exactly 2 arguments (3 given)

Use the correct number of arguments for self.warning and print the
original exception to stderr.
2013-01-31 08:20:33 +01:00
Claudio Bley
790d364ca2 docs: fix missed documentation for virterror functions
Commit f24404a324 renamed virterror.c to
virerror.c but forgot to change the reference in this file.
2013-01-30 07:53:14 +01:00
Jiri Denemark
1640fafc6a docs: Generate documentation for virTypedParams* APIs 2013-01-21 18:41:26 +01:00
Jiri Denemark
c72e327456 docs: event.c source file was renamed as virevent.c 2013-01-21 18:40:28 +01:00
Daniel P. Berrange
3d1596b048 Introduce an LXC specific public API & library
This patch introduces support for LXC specific public APIs. In
common with what was done for QEMU, this creates a libvirt_lxc.so
library and libvirt/libvirt-lxc.h header file.

The actual APIs are

  int virDomainLxcOpenNamespace(virDomainPtr domain,
                                int **fdlist,
                                unsigned int flags);

  int virDomainLxcEnterNamespace(virDomainPtr domain,
                                 unsigned int nfdlist,
                                 int *fdlist,
                                 unsigned int *noldfdlist,
                                 int **oldfdlist,
                                 unsigned int flags);

which provide a way to use the setns() system call to move the
calling process into the container's namespace. It is not
practical to write in a generically applicable manner. The
nearest that we could get to such an API would be an API which
allows to pass a command + argv to be executed inside a
container. Even if we had such a generic API, this LXC specific
API is still useful, because it allows the caller to maintain
the current process context, in particular any I/O streams they
have open.

NB the virDomainLxcEnterNamespace() API is special in that it
runs client side, so does not involve the internal driver API.

Signed-off-by: Daniel P. Berrange <berrange@redhat.com>
2013-01-14 13:58:34 +00:00
Claudio Bley
bf1786b6d5 docs: restrict the set of characters for info keys
When parsing the top level comment of a file, apibuild.py used
to split on any ':' character of a line regarding the first part
as a key for a setting, e.g. "Summary". The second part would then
be assigned as the value for that key.

This means you could not use a ':' character inside those comments
without ill effects.

Now, a key must consist solely of alphanumeric characters, '_' or '.'.
2013-01-14 09:18:43 +01:00
Claudio Bley
833e1493ed docs: simplify code 2013-01-14 09:18:43 +01:00
Claudio Bley
1e8b4b5810 docs: remove duplicate check in index.add 2013-01-08 11:45:47 +01:00
Ján Tomko
149c87b49d Various typos and misspellings 2012-10-12 00:03:43 +02:00
Eric Blake
ef1e024df8 blockjob: add virDomainBlockCommit
A block commit moves data in the opposite direction of block pull.
Block pull reduces the chain length by dropping backing files after
data has been pulled into the top overlay, and is always safe; block
commit reduces the chain length by dropping overlays after data has
been committed into the backing file, and any files that depended
on base but not on top are invalidated at any point where they have
unallocated data that is now pointing to changed contents in base.
Both directions are useful, however: a qcow2 layer that is more than
50% allocated will typically be faster with a pull operation, while
a qcow2 layer with less than 50% allocation will be faster as a
commit operation.  Committing across multiple layers can be more
efficient than repeatedly committing one layer at a time, but
requires extra support from the hypervisor.

This API matches Jeff Cody's proposed qemu command 'block-commit':
https://lists.gnu.org/archive/html/qemu-devel/2012-09/msg02226.html

Jeff's command is still in the works for qemu 1.3, and may gain
further enhancements, such as the ability to control on-error
handling (it will be comparable to the error handling Paolo is
adding to 'drive-mirror', so a similar solution will be needed
when I finally propose virDomainBlockCopy with more functionality
than the basics supported by virDomainBlockRebase).  However, even
without qemu support, this API will be useful for _offline_ block
commits, by wrapping qemu-img calls and turning them into a block
job, so this API is worth committing now.

For some examples of how this will be implemented, all starting
with the chain: base <- snap1 <- snap2 <- active

+ These are equivalent:
 virDomainBlockCommit(dom, disk, NULL, NULL, 0, 0)
 virDomainBlockCommit(dom, disk, NULL, "active", 0, 0)
 virDomainBlockCommit(dom, disk, "base", NULL, 0, 0)
 virDomainBlockCommit(dom, disk, "base", "active", 0, 0)
but cannot be implemented for online qemu with round 1 of
Jeff's patches; and for offline images, it would require
three back-to-back qemu-img invocations unless qemu-img
is patched to allow more efficient multi-layer commits;
the end result would be 'base' as the active disk with
contents from all three other files, where 'snap1' and
'snap2' are invalid right away, and 'active' is invalid
once any further changes to 'base' are made.

+ These are equivalent:
 virDomainBlockCommit(dom, disk, "snap2", NULL, 0, 0)
 virDomainBlockCommit(dom, disk, NULL, NULL, 0, _SHALLOW)
they cannot be implemented for online qemu, but for offline,
it is a matter of 'qemu-img commit active', so that 'snap2'
is now the active disk with contents formerly in 'active'.

+ Similarly:
 virDomainBlockCommit(dom, disk, "snap2", NULL, 0, _DELETE)
for an offline domain will merge 'active' into 'snap2', then
delete 'active' to avoid leaving a potentially invalid file
around.

+ This version:
 virDomainBlockCommit(dom, disk, NULL, "snap2", 0, _SHALLOW)
can be implemented online with 'block-commit' passing a base of
snap1 and a top of snap2; and can be implemented offline by
'qemu-img commit snap2' followed by 'qemu-img rebase -u
-b snap1 active'

* include/libvirt/libvirt.h.in (virDomainBlockCommit): New API.
* src/libvirt.c (virDomainBlockCommit): Implement it.
* src/libvirt_public.syms (LIBVIRT_0.10.2): Export it.
* src/driver.h (virDrvDomainBlockCommit): New driver callback.
* docs/apibuild.py (CParser.parseSignature): Add exception.
2012-09-17 21:28:08 -06:00
Peter Krempa
b889bac171 docs: Add method to print warnings in docBuilder class
The method was not existing and did not allow to diagnose problems.
2012-07-27 15:47:15 +02:00
Daniel P. Berrange
45b43a8cab Add parsing for VIR_ENUM_IMPL & VIR_ENUM_DECL in apibuild.py
The apibuild.py parser needs to be able to parse & ignore
any VIR_ENUM_IMPL/VIR_ENUM_DECL macros in the source. Add
some special case code to deal with this rather than trying
to figure out a generic syntax for parsing macros.

* apibuild.py: Special case  VIR_ENUM_IMPL & VIR_ENUM_DECL
2012-05-24 16:20:55 +01:00