[Libvir] Documentation errors and shortcomings

[Richard W.M. Jones]

Tóth István wrote:
> I believe that the fields of these structs ARE meant to be read by the
> applications linking the library,  and are not really meant to be
> opaque. (or if they are, they should have some functions/macros that you
> can access their contents with)

Yes, you should access the fields directly.

If an individual stats field isn't supported by the hypervisor, it will 
be returned as ((long long) -1) [for various reasons we're using long 
long here, but really we mean 64 bit signed int].

If a field is returned as 0, that means "no activity".  However I have 
noticed there is a problem with fullvirt domains on Xen 3.0.3 which 
means that network stats are reported as 0.  I don't understand yet what 
causes this problem, but obviously it's a bug somewhere, seemingly in 
Xen itself.  The code works fine with recent Xen hypervisors.

If the hypervisor doesn't support stats collection at all then you'll 
get an error from the function call (ie. the function itself will return 
-1).  At the moment the functions aren't supported on QEMU or KVM at 
all, something which really needs to be fixed as soon as possible.  They 
also have rather partial support on Xen, in particular fullvirt Xen 
domains cannot return disk stats for what is essentially a very trivial 
reason which could be fixed in about 3 lines of code.  For updated 
status, please track this page: http://libvirt.org/hvsupport.html

You have to pass the size of the structure to the calls.  This allows us 
to extend the structure in future with additional fields, but also to 
detect the new caller / old libvirt case and avoid a segfault.  Such are 
the joys of type unsafe dynamic linking.

To see these functions being called from C code, go to the following 
page and search down for 'ocaml_libvirt_domain_block_stats' and 
'ocaml_libvirt_domain_interface_stats'.

http://hg.et.redhat.com/virt/applications/virt-top--devel?f=da16c97fea65;file=libvirt/libvirt_c.c

Daniel Veillard has fixed the missing typedef problem in CVS.

Rich.

-- 
Emerging Technologies, Red Hat - http://et.redhat.com/~rjones/
Registered Address: Red Hat UK Ltd, Amberley Place, 107-111 Peascod
Street, Windsor, Berkshire, SL4 1TE, United Kingdom.  Registered in
England and Wales under Company Registration No. 03798903

-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/x-pkcs7-signature
Size: 3237 bytes
Desc: S/MIME Cryptographic Signature
URL: <http://listman.redhat.com/archives/libvir-list/attachments/20070910/cc6ecb83/attachment-0001.bin>