[PATCH v2 00/23] Add typed param constants for guest info and domain stats APIs

Contrary to most APIs returning typed parameters, there are no constants defined for the domain stats data keys. This is was because many of the keys needs to be dynamically constructed using one or more array index values. It is possible to define constants while still supporting dynamic array indexes by simply defining the prefixes and suffixes as constants. The consuming code can then combine the constants with array index value. With this approach, it is practical to add constants for the domain stats API keys. The pattern for array entries is as follows * VIR_DOMAIN_GUEST_INFO_blah_COUNT - the number of items in the array * VIR_DOMAIN_GUEST_INFO_blah_PREFIX - the key prefix, including the trailing '.' - eg "disk." * VIR_DOMAIN_GUEST_INFO_blah_SUFFIX_blah - the key suffix, including the leading '.' - eg ".name" Where there are nested arrays, this repeats in the natural way * VIR_DOMAIN_GUEST_INFO_blah_SUFFIX_blah_COUNT - the number of items in the array * VIR_DOMAIN_GUEST_INFO_blah_SUFFIX_blah_PREFIX - the key prefix, including the leading and trailing '.' - eg ".addr." * VIR_DOMAIN_GUEST_INFO_blah_SUFFIX_blah_SUFFIX_blah - the key suffix, including the leading '.' - eg ".name" A usage of this would look like, relying on CPP string concatenation asprintf(&str, VIR_DOMAIN_STATS_VCPU_PREFIX "%d" VIR_DOMAIN_STATS_VCPU_SUFFIX_DELAY, idx); Or in language bindings such as Golang fmt.Sprintf(C.VIR_DOMAIN_STATS_VCPU_PREFIX+"%d"+C.VIR_DOMAIN_STATS_VCPU_SUFFIX_HALTED, idx) Adding these constants has a few benefits: * We can ensure that different drivers are all consistent in keys used for typed parameters * Language bindings can query the API XML to identify any gaps in their API coverage A note on "Since" tags. We use the "Since" tags to express when an API was added to libvirt. In this case we're adding constants long /after/ we first introduced these APIs. So the question is whether the Since tags reflect when the typed parameter key was first used or when the API constant was added. For convenience I chose the latter, because the Golang bnidings use the Since tags to auto generate code with #if !LIBVIRT_CHECK_VERSION() around its usage of the constants. This would break if we retroactively dated the Since tags to when the keys were first used. As proof of the value, adding these constants has lead to be find sooooooooooo many mistakes in the Golang bindings where we forgot to add new domain stats/guest info data items, and one place where we typod the name. https://gitlab.com/libvirt/libvirt-go-module/-/merge_requests/67 Changes in v2: * Don't line wrap concatenation of the macros * Fix a couple of typos in constants * Rebase for changes to virt typed paramater list API usage in guest info * Add docs explaining the usage pattern * Add docs explaining the 11.2.0 version number caveat vs historical introduction Daniel P. Berrangé (23): src: add constants for guest info 'user.' parameters src: add constants for guest info 'os.' parameters src: add constants for guest info 'timezone.' parameters src: add constant for the guest info 'hostname' parameter src: add constants for guest info 'fs.' parameters src: add constants for guest info 'disk.' parameters src: add constants for guest info 'if.' parameters src: add constants for guest info 'load.' parameters src: expand docs for guest info array handling src: expand docs for guest info constant version handling src: add constants for domain stats 'state.' parameters src: add constants for domain stats 'cpu.' parameters src: add constants for domain stats 'balloon.' parameters src: add constants for domain stats 'vcpu.' parameters src: add constants for domain stats 'net.' parameters src: add constants for domain stats 'block.' parameters src: add constants for domain stats 'perf.' parameters src: add constants for domain stats 'iothread.' parameters src: add constants for domain stats 'memory.' parameters src: add constants for domain stats 'dirtyrate.' parameters src: document that no constants are provided for custom VM stats src: expand docs for guest info array handling src: expand docs for guest stats constant version handling include/libvirt/libvirt-domain.h | 6605 +++++++++++++++++++----------- src/libvirt-domain.c | 547 +-- src/qemu/qemu_agent.c | 35 +- src/qemu/qemu_driver.c | 377 +- 4 files changed, 4573 insertions(+), 2991 deletions(-) -- 2.48.1