[libvirt PATCH 0/4] scripts: improve API docs handing of enums
In attempting to refactor the Go API bindings to be partially
auto-generated, I'm encountering missing information in the enum
descriptions.
The effects of this series are shown in this diff:
--- libvirt-api.xml 2020-05-19 12:47:22.003489289 +0100
+++ docs/libvirt-api.xml 2020-05-19 12:47:27.156476186 +0100
@@ -1,4 +1,4 @@
-<?xml version=3D"1.0" encoding=3D"ISO-8859-1"?>
+<?xml version=3D"1.0" encoding=3D"UTF-8"?>
<api name=3D'libvirt'>
<files>
<file name=3D'libvirt-domain-checkpoint'>
@@ -2089,13 +2089,13 @@
</file>
</files>
<symbols>
- <macro name=3D'LIBVIR_CHECK_VERSION' file=3D'libvirt-common'>
+ <macro name=3D'LIBVIR_CHECK_VERSION' file=3D'libvirt-common' params=3D'm=
ajor,minor,micro' raw=3D'((major) * 1000000 + (minor) * 1000 + (micro) <=3D L=
IBVIR_VERSION_NUMBER)'>
<info><![CDATA[Macro for developers to easily check what version of th=
e library their code is compiling against. e.g. #if LIBVIR_CHECK_VERSION(1,1,=
3) // some code that only works in 1.1.3 and newer #endif]]></info>
<arg name=3D'major' info=3D'major component of the version number'/>
<arg name=3D'minor' info=3D'minor component of the version number'/>
<arg name=3D'micro' info=3D'micro component of the version number'/>
</macro>
- <macro name=3D'LIBVIR_VERSION_NUMBER' file=3D'libvirt-common'>
+ <macro name=3D'LIBVIR_VERSION_NUMBER' file=3D'libvirt-common' raw=3D'600=
4000'>
<info><![CDATA[Macro providing the version of the library as version *=
1,000,000 + minor * 1000 + micro]]></info>
</macro>
<macro name=3D'VIR_CONNECT_IDENTITY_GROUP_NAME' file=3D'libvirt-host' st=
ring=3D'group-name'>
@@ -2125,25 +2125,25 @@
<macro name=3D'VIR_CONNECT_IDENTITY_X509_DISTINGUISHED_NAME' file=3D'lib=
virt-host' string=3D'x509-distinguished-name'>
<info><![CDATA[The TLS x509 certificate distinguished named as VIR_TYP=
ED_PARAM_STRING]]></info>
</macro>
- <macro name=3D'VIR_COPY_CPUMAP' file=3D'libvirt-domain'>
+ <macro name=3D'VIR_COPY_CPUMAP' file=3D'libvirt-domain' params=3D'cpumap=
s,maplen,vcpu,cpumap' raw=3D'memcpy(cpumap, VIR_GET_CPUMAP(cpumaps, maplen, v=
cpu), maplen)'>
<info><![CDATA[This macro is to be used in conjunction with virDomainG=
etVcpus() and virDomainPinVcpu() APIs. VIR_COPY_CPUMAP macro extracts the cpu=
map of the specified vcpu from cpumaps array and copies it into cpumap to be =
used later by virDomainPinVcpu() API.]]></info>
<arg name=3D'cpumaps' info=3D'pointer to an array of cpumap (in 8-bit =
bytes) (IN)'/>
<arg name=3D'maplen' info=3D'the length (in bytes) of one cpumap'/>
<arg name=3D'vcpu' info=3D'the virtual CPU number'/>
<arg name=3D'cpumap' info=3D'pointer to a cpumap (in 8-bit bytes) (OUT=
) This cpumap must be previously allocated by the caller (ie: malloc(maplen))=
'/>
</macro>
- <macro name=3D'VIR_CPU_MAPLEN' file=3D'libvirt-domain'>
+ <macro name=3D'VIR_CPU_MAPLEN' file=3D'libvirt-domain' params=3D'cpu' ra=
w=3D''>
<info><![CDATA[This macro is to be used in conjunction with virDomainP=
inVcpu() API. It returns the length (in bytes) required to store the complete=
CPU map between a single virtual & all physical CPUs of a domain.]]></info>
<arg name=3D'cpu' info=3D'number of physical CPUs'/>
</macro>
- <macro name=3D'VIR_CPU_USABLE' file=3D'libvirt-domain'>
+ <macro name=3D'VIR_CPU_USABLE' file=3D'libvirt-domain' params=3D'cpumaps=
,maplen,vcpu,cpu' raw=3D'VIR_CPU_USED(VIR_GET_CPUMAP(cpumaps, maplen, vcpu), =
cpu)'>
<info><![CDATA[This macro is to be used in conjunction with virDomainG=
etVcpus() API. VIR_CPU_USABLE macro returns a non-zero value (true) if the cp=
u is usable by the vcpu, and 0 otherwise.]]></info>
<arg name=3D'cpumaps' info=3D'pointer to an array of cpumap (in 8-bit =
bytes) (IN)'/>
<arg name=3D'maplen' info=3D'the length (in bytes) of one cpumap'/>
<arg name=3D'vcpu' info=3D'the virtual CPU number'/>
<arg name=3D'cpu' info=3D'the physical CPU number'/>
</macro>
- <macro name=3D'VIR_CPU_USED' file=3D'libvirt-domain'>
+ <macro name=3D'VIR_CPU_USED' file=3D'libvirt-domain' params=3D'cpumap,cp=
u' raw=3D'((cpumap)[(cpu) / 8] & (1 << ((cpu) % 8)))'>
<info><![CDATA[This macro can be used in conjunction with virNodeGetCP=
UMap() API. It returns non-zero if the bit of the related CPU is set.]]></inf=
o>
<arg name=3D'cpumap' info=3D'pointer to a bit map of real CPUs (in 8-b=
it bytes) (IN)'/>
<arg name=3D'cpu' info=3D'the physical CPU number'/>
@@ -2184,7 +2184,7 @@
<macro name=3D'VIR_DOMAIN_BLKIO_DEVICE_WRITE_IOPS' file=3D'libvirt-domai=
n' string=3D'device_write_iops_sec'>
<info><![CDATA[Macro for the blkio tunable throttle.write_iops_device:=
it represents the number of writing the block device per second, as a string=
. The string is parsed as a series of /path/to/device, write_iops elements, s=
eparated by ','.]]></info>
</macro>
- <macro name=3D'VIR_DOMAIN_BLKIO_FIELD_LENGTH' file=3D'libvirt-domain'>
+ <macro name=3D'VIR_DOMAIN_BLKIO_FIELD_LENGTH' file=3D'libvirt-domain' ra=
w=3D'VIR_TYPED_PARAM_FIELD_LENGTH'>
<info><![CDATA[Macro providing the field length of virBlkioParameter. =
Provided for backwards compatibility; VIR_TYPED_PARAM_FIELD_LENGTH is the pr=
eferred value since 0.9.2.]]></info>
</macro>
<macro name=3D'VIR_DOMAIN_BLKIO_WEIGHT' file=3D'libvirt-domain' string=
=3D'weight'>
@@ -2262,7 +2262,7 @@
<macro name=3D'VIR_DOMAIN_BLOCK_STATS_ERRS' file=3D'libvirt-domain' stri=
ng=3D'errs'>
<info><![CDATA[In Xen this returns the mysterious 'oo_req', as an llon=
g.]]></info>
</macro>
- <macro name=3D'VIR_DOMAIN_BLOCK_STATS_FIELD_LENGTH' file=3D'libvirt-doma=
in'>
+ <macro name=3D'VIR_DOMAIN_BLOCK_STATS_FIELD_LENGTH' file=3D'libvirt-doma=
in' raw=3D'VIR_TYPED_PARAM_FIELD_LENGTH'>
<info><![CDATA[Macro providing the field length of parameter names whe=
n using virDomainBlockStatsFlags().]]></info>
</macro>
<macro name=3D'VIR_DOMAIN_BLOCK_STATS_FLUSH_REQ' file=3D'libvirt-domain'=
string=3D'flush_operations'>
@@ -2301,7 +2301,7 @@
<macro name=3D'VIR_DOMAIN_CPU_STATS_VCPUTIME' file=3D'libvirt-domain' st=
ring=3D'vcpu_time'>
<info><![CDATA[vcpu usage in nanoseconds (cpu_time excluding hyperviso=
r time), as a ullong]]></info>
</macro>
- <macro name=3D'VIR_DOMAIN_EVENT_CALLBACK' file=3D'libvirt-domain'>
+ <macro name=3D'VIR_DOMAIN_EVENT_CALLBACK' file=3D'libvirt-domain' params=
=3D'cb' raw=3D''>
<info><![CDATA[Used to cast the event specific callback into the gener=
ic one for use for virConnectDomainEventRegisterAny()]]></info>
</macro>
<macro name=3D'VIR_DOMAIN_IOTHREAD_POLL_GROW' file=3D'libvirt-domain' st=
ring=3D'poll_grow'>
@@ -2421,7 +2421,7 @@
<macro name=3D'VIR_DOMAIN_LAUNCH_SECURITY_SEV_MEASUREMENT' file=3D'libvi=
rt-domain' string=3D'sev-measurement'>
<info><![CDATA[Macro represents the launch measurement of the SEV gues=
t, as VIR_TYPED_PARAM_STRING.]]></info>
</macro>
- <macro name=3D'VIR_DOMAIN_MEMORY_FIELD_LENGTH' file=3D'libvirt-domain'>
+ <macro name=3D'VIR_DOMAIN_MEMORY_FIELD_LENGTH' file=3D'libvirt-domain' r=
aw=3D'VIR_TYPED_PARAM_FIELD_LENGTH'>
<info><![CDATA[Macro providing the field length of virMemoryParameter.=
Provided for backwards compatibility; VIR_TYPED_PARAM_FIELD_LENGTH is the p=
referred value since 0.9.2.]]></info>
</macro>
<macro name=3D'VIR_DOMAIN_MEMORY_HARD_LIMIT' file=3D'libvirt-domain' str=
ing=3D'hard_limit'>
@@ -2430,7 +2430,7 @@
<macro name=3D'VIR_DOMAIN_MEMORY_MIN_GUARANTEE' file=3D'libvirt-domain' =
string=3D'min_guarantee'>
<info><![CDATA[Macro for the memory tunable min_guarantee: it represen=
ts the minimum memory guaranteed to be reserved for the guest, as a ullong.]]=
></info>
</macro>
- <macro name=3D'VIR_DOMAIN_MEMORY_PARAM_UNLIMITED' file=3D'libvirt-domain=
'>
+ <macro name=3D'VIR_DOMAIN_MEMORY_PARAM_UNLIMITED' file=3D'libvirt-domain=
' raw=3D'9007199254740991LL /* =3D INT64_MAX >> 10 */'>
<info><![CDATA[Macro providing the virMemoryParameter value that indic=
ates "unlimited"]]></info>
</macro>
<macro name=3D'VIR_DOMAIN_MEMORY_SOFT_LIMIT' file=3D'libvirt-domain' str=
ing=3D'soft_limit'>
@@ -2487,10 +2487,10 @@
<macro name=3D'VIR_DOMAIN_SCHEDULER_WEIGHT' file=3D'libvirt-domain' stri=
ng=3D'weight'>
<info><![CDATA[Macro represents the relative weight, when using the c=
redit scheduler, as a uint.]]></info>
</macro>
- <macro name=3D'VIR_DOMAIN_SCHED_FIELD_LENGTH' file=3D'libvirt-domain'>
+ <macro name=3D'VIR_DOMAIN_SCHED_FIELD_LENGTH' file=3D'libvirt-domain' ra=
w=3D'VIR_TYPED_PARAM_FIELD_LENGTH'>
<info><![CDATA[Macro providing the field length of virSchedParameter. =
Provided for backwards compatibility; VIR_TYPED_PARAM_FIELD_LENGTH is the pr=
eferred value since 0.9.2.]]></info>
</macro>
- <macro name=3D'VIR_DOMAIN_SEND_KEY_MAX_KEYS' file=3D'libvirt-domain'>
+ <macro name=3D'VIR_DOMAIN_SEND_KEY_MAX_KEYS' file=3D'libvirt-domain' raw=
=3D'16'>
<info><![CDATA[Maximum number of keycodes that can be sent in one virD=
omainSendKey() call.]]></info>
</macro>
<macro name=3D'VIR_DOMAIN_TUNABLE_BLKDEV_DISK' file=3D'libvirt-domain' s=
tring=3D'blkdeviotune.disk'>
@@ -2592,13 +2592,13 @@
<macro name=3D'VIR_DOMAIN_TUNABLE_CPU_VCPU_QUOTA' file=3D'libvirt-domain=
' string=3D'cputune.vcpu_quota'>
<info><![CDATA[Macro represents the maximum bandwidth to be used withi=
n a period for vcpus only, when using the posix scheduler, as VIR_TYPED_PARAM=
_LLONG.]]></info>
</macro>
- <macro name=3D'VIR_GET_CPUMAP' file=3D'libvirt-domain'>
+ <macro name=3D'VIR_GET_CPUMAP' file=3D'libvirt-domain' params=3D'cpumaps=
,maplen,vcpu' raw=3D'(&((cpumaps)[(vcpu) * (maplen)]))'>
<info><![CDATA[This macro is to be used in conjunction with virDomainG=
etVcpus() and virDomainPinVcpu() APIs. VIR_GET_CPUMAP macro returns a pointer=
to the cpumap of the specified vcpu from cpumaps array.]]></info>
<arg name=3D'cpumaps' info=3D'pointer to an array of cpumap (in 8-bit =
bytes) (IN)'/>
<arg name=3D'maplen' info=3D'the length (in bytes) of one cpumap'/>
<arg name=3D'vcpu' info=3D'the virtual CPU number'/>
</macro>
- <macro name=3D'VIR_KEYCODE_SET_RFB' file=3D'libvirt-domain'>
+ <macro name=3D'VIR_KEYCODE_SET_RFB' file=3D'libvirt-domain' raw=3D'VIR_K=
EYCODE_SET_QNUM'>
<info><![CDATA[Compatibility alias for VIR_KEYCODE_SET_QNUM, which rep=
laced it since 4.2.0.]]></info>
</macro>
<macro name=3D'VIR_MIGRATE_PARAM_AUTO_CONVERGE_INCREMENT' file=3D'libvir=
t-domain' string=3D'auto_converge.increment'>
@@ -2658,7 +2658,7 @@
<macro name=3D'VIR_MIGRATE_PARAM_URI' file=3D'libvirt-domain' string=3D'=
migrate_uri'>
<info><![CDATA[virDomainMigrate* params field: URI to use for initiati=
ng domain migration as VIR_TYPED_PARAM_STRING. It takes a hypervisor specific=
format. The uri_transports element of the hypervisor capabilities XML includ=
es details of the supported URI schemes. When omitted libvirt will auto-gener=
ate suitable default URI. It is typically only necessary to specify this URI =
if the destination host has multiple interfaces and a specific interface is r=
equired to transmit migration data. This field may not be used when VIR_MIGR=
ATE_TUNNELLED flag is set.]]></info>
</macro>
- <macro name=3D'VIR_NETWORK_EVENT_CALLBACK' file=3D'libvirt-network'>
+ <macro name=3D'VIR_NETWORK_EVENT_CALLBACK' file=3D'libvirt-network' para=
ms=3D'cb' raw=3D''>
<info><![CDATA[Used to cast the event specific callback into the gener=
ic one for use for virConnectNetworkEventRegisterAny()]]></info>
</macro>
<macro name=3D'VIR_NETWORK_PORT_BANDWIDTH_IN_AVERAGE' file=3D'libvirt-ne=
twork' string=3D'inbound.average'>
@@ -2682,11 +2682,11 @@
<macro name=3D'VIR_NETWORK_PORT_BANDWIDTH_OUT_PEAK' file=3D'libvirt-netw=
ork' string=3D'outbound.peak'>
<info><![CDATA[Macro represents the outbound peak of NIC bandwidth, as=
a uint.]]></info>
</macro>
- <macro name=3D'VIR_NODEINFO_MAXCPUS' file=3D'libvirt-host'>
+ <macro name=3D'VIR_NODEINFO_MAXCPUS' file=3D'libvirt-host' params=3D'nod=
einfo' raw=3D''>
<info><![CDATA[This macro is to calculate the total number of CPUs sup=
ported but not necessary active in the host.]]></info>
<arg name=3D'nodeinfo' info=3D'virNodeInfo instance'/>
</macro>
- <macro name=3D'VIR_NODE_CPU_STATS_FIELD_LENGTH' file=3D'libvirt-host'>
+ <macro name=3D'VIR_NODE_CPU_STATS_FIELD_LENGTH' file=3D'libvirt-host' ra=
w=3D'80'>
<info><![CDATA[Macro providing the field length of virNodeCPUStats]]><=
/info>
</macro>
<macro name=3D'VIR_NODE_CPU_STATS_IDLE' file=3D'libvirt-host' string=3D'=
idle'>
@@ -2707,7 +2707,7 @@
<macro name=3D'VIR_NODE_CPU_STATS_UTILIZATION' file=3D'libvirt-host' str=
ing=3D'utilization'>
<info><![CDATA[The CPU utilization of a node. The usage value is in pe=
rcent and 100% represents all CPUs of the node.]]></info>
</macro>
- <macro name=3D'VIR_NODE_DEVICE_EVENT_CALLBACK' file=3D'libvirt-nodedev'>
+ <macro name=3D'VIR_NODE_DEVICE_EVENT_CALLBACK' file=3D'libvirt-nodedev' =
params=3D'cb' raw=3D'((virConnectNodeDeviceEventGenericCallback)(cb))'>
<info><![CDATA[Used to cast the event specific callback into the gener=
ic one for use for virConnectNodeDeviceEventRegisterAny()]]></info>
</macro>
<macro name=3D'VIR_NODE_MEMORY_SHARED_FULL_SCANS' file=3D'libvirt-host' =
string=3D'shm_full_scans'>
@@ -2740,7 +2740,7 @@
<macro name=3D'VIR_NODE_MEMORY_STATS_CACHED' file=3D'libvirt-host' strin=
g=3D'cached'>
<info><![CDATA[Macro for the cached memory: On Linux, it is only retur=
ned in case of VIR_NODE_MEMORY_STATS_ALL_CELLS.]]></info>
</macro>
- <macro name=3D'VIR_NODE_MEMORY_STATS_FIELD_LENGTH' file=3D'libvirt-host'>
+ <macro name=3D'VIR_NODE_MEMORY_STATS_FIELD_LENGTH' file=3D'libvirt-host'=
raw=3D'80'>
<info><![CDATA[Macro providing the field length of virNodeMemoryStats]=
]></info>
</macro>
<macro name=3D'VIR_NODE_MEMORY_STATS_FREE' file=3D'libvirt-host' string=
=3D'free'>
@@ -2827,45 +2827,45 @@
<macro name=3D'VIR_PERF_PARAM_TASK_CLOCK' file=3D'libvirt-domain' string=
=3D'task_clock'>
<info><![CDATA[Macro for typed parameter name that represents task_clo=
ck perf event which can be used to measure the count of task clock time by ap=
plications running on the platform. It corresponds to the "perf.task_clock" f=
ield in the *Stats APIs.]]></info>
</macro>
- <macro name=3D'VIR_SECRET_EVENT_CALLBACK' file=3D'libvirt-secret'>
+ <macro name=3D'VIR_SECRET_EVENT_CALLBACK' file=3D'libvirt-secret' params=
=3D'cb' raw=3D'((virConnectSecretEventGenericCallback)(cb))'>
<info><![CDATA[Used to cast the event specific callback into the gener=
ic one for use for virConnectSecretEventRegisterAny()]]></info>
</macro>
- <macro name=3D'VIR_SECURITY_DOI_BUFLEN' file=3D'libvirt-host'>
+ <macro name=3D'VIR_SECURITY_DOI_BUFLEN' file=3D'libvirt-host' raw=3D'(25=
6 + 1)'>
<info><![CDATA[Macro providing the maximum length of the virSecurityMo=
del doi string.]]></info>
</macro>
- <macro name=3D'VIR_SECURITY_LABEL_BUFLEN' file=3D'libvirt-host'>
+ <macro name=3D'VIR_SECURITY_LABEL_BUFLEN' file=3D'libvirt-host' raw=3D'(=
4096 + 1)'>
<info><![CDATA[Macro providing the maximum length of the virSecurityLa=
bel label string. Note that this value is based on that used by Labeled NFS.]=
]></info>
</macro>
- <macro name=3D'VIR_SECURITY_MODEL_BUFLEN' file=3D'libvirt-host'>
+ <macro name=3D'VIR_SECURITY_MODEL_BUFLEN' file=3D'libvirt-host' raw=3D'(=
256 + 1)'>
<info><![CDATA[Macro providing the maximum length of the virSecurityMo=
del model string.]]></info>
</macro>
- <macro name=3D'VIR_STORAGE_POOL_EVENT_CALLBACK' file=3D'libvirt-storage'>
+ <macro name=3D'VIR_STORAGE_POOL_EVENT_CALLBACK' file=3D'libvirt-storage'=
params=3D'cb' raw=3D'((virConnectStoragePoolEventGenericCallback)(cb))'>
<info><![CDATA[Used to cast the event specific callback into the gener=
ic one for use for virConnectStoragePoolEventRegisterAny()]]></info>
</macro>
- <macro name=3D'VIR_TYPED_PARAM_FIELD_LENGTH' file=3D'libvirt-common'>
+ <macro name=3D'VIR_TYPED_PARAM_FIELD_LENGTH' file=3D'libvirt-common' raw=
=3D'80'>
<info><![CDATA[Macro providing the field length of virTypedParameter n=
ame]]></info>
</macro>
- <macro name=3D'VIR_UNUSE_CPU' file=3D'libvirt-domain'>
+ <macro name=3D'VIR_UNUSE_CPU' file=3D'libvirt-domain' params=3D'cpumap,c=
pu' raw=3D'((cpumap)[(cpu) / 8] &=3D ~(1 << ((cpu) % 8)))'>
<info><![CDATA[This macro is to be used in conjunction with virDomainP=
inVcpu() API. It resets the bit (CPU not usable) of the related cpu in cpumap=
.]]></info>
<arg name=3D'cpumap' info=3D'pointer to a bit map of real CPUs (in 8-b=
it bytes) (IN/OUT)'/>
<arg name=3D'cpu' info=3D'the physical CPU number'/>
</macro>
- <macro name=3D'VIR_USE_CPU' file=3D'libvirt-domain'>
+ <macro name=3D'VIR_USE_CPU' file=3D'libvirt-domain' params=3D'cpumap,cpu=
' raw=3D'((cpumap)[(cpu) / 8] |=3D (1 << ((cpu) % 8)))'>
<info><![CDATA[This macro is to be used in conjunction with virDomainP=
inVcpu() API. It sets the bit (CPU usable) of the related cpu in cpumap.]]></=
info>
<arg name=3D'cpumap' info=3D'pointer to a bit map of real CPUs (in 8-b=
it bytes) (IN/OUT)'/>
<arg name=3D'cpu' info=3D'the physical CPU number'/>
</macro>
- <macro name=3D'VIR_UUID_BUFLEN' file=3D'libvirt-host'>
+ <macro name=3D'VIR_UUID_BUFLEN' file=3D'libvirt-host' raw=3D'(16)'>
<info><![CDATA[This macro provides the length of the buffer required f=
or virDomainGetUUID()]]></info>
</macro>
- <macro name=3D'VIR_UUID_STRING_BUFLEN' file=3D'libvirt-host'>
+ <macro name=3D'VIR_UUID_STRING_BUFLEN' file=3D'libvirt-host' raw=3D'(36+=
1)'>
<info><![CDATA[This macro provides the length of the buffer required f=
or virDomainGetUUIDString()]]></info>
</macro>
- <macro name=3D'_virBlkioParameter' file=3D'libvirt-domain'>
+ <macro name=3D'_virBlkioParameter' file=3D'libvirt-domain' raw=3D'_virTy=
pedParameter'>
</macro>
- <macro name=3D'_virMemoryParameter' file=3D'libvirt-domain'>
+ <macro name=3D'_virMemoryParameter' file=3D'libvirt-domain' raw=3D'_virT=
ypedParameter'>
</macro>
- <macro name=3D'_virSchedParameter' file=3D'libvirt-domain'>
+ <macro name=3D'_virSchedParameter' file=3D'libvirt-domain' raw=3D'_virTy=
pedParameter'>
</macro>
<enum name=3D'VIR_CONNECT_BASELINE_CPU_EXPAND_FEATURES' file=3D'libvirt-=
host' value=3D'1' value_hex=3D'0x1' value_bitshift=3D'0' type=3D'virConnectBa=
selineCPUFlags' info=3D'show all features'/>
<enum name=3D'VIR_CONNECT_BASELINE_CPU_MIGRATABLE' file=3D'libvirt-host'=
value=3D'2' value_hex=3D'0x2' value_bitshift=3D'1' type=3D'virConnectBaselin=
eCPUFlags' info=3D'filter out non-migratable features'/>
Daniel P. Berrang=C3=A9 (4):
scripts: use UTF-8 for API XML files
scripts: fix tokenizing of enum parameters in API builder
scripts: emit enum parameters in API build description
scripts: emit raw enum value in API build description
scripts/apibuild.py | 47 ++++++++++++++++++++++++++++++++++++++-------
1 file changed, 40 insertions(+), 7 deletions(-)
--=20
2.26.2
The build system will be running in UTF-8 locale, so any content in the API XML files will also end up being UTF-8, not ISO-8859-1. Signed-off-by: Daniel P. Berrangé <berrange@redhat.com> --- scripts/apibuild.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/apibuild.py b/scripts/apibuild.py index 05a169c30d..b13b5db644 100755 --- a/scripts/apibuild.py +++ b/scripts/apibuild.py @@ -2333,7 +2333,7 @@ class docBuilder: if not quiet: print("Saving XML description %s" % (filename)) output = open(filename, "w") - output.write('<?xml version="1.0" encoding="ISO-8859-1"?>\n') + output.write('<?xml version="1.0" encoding="UTF-8"?>\n') output.write("<api name='%s'>\n" % self.name) output.write(" <files>\n") headers = sorted(self.headers.keys()) -- 2.26.2
The API build script tokenizes enums declarations by first splitting on whitespace. This is unhelpful as it means an enum # define VIR_USE_CPU(cpumap, cpu) ((cpumap)[(cpu) / 8] |= (1 << ((cpu) % 8))) Gets tokenized as #define VIR_USE_CPU(cpumap, cpu) ((cpumap)[(cpu) / 8] |= (1 << ((cpu) % 8))) With this change, the set of parameters are all merged into the first token: #define VIR_USE_CPU(cpumap,cpu) ((cpumap)[(cpu) / 8] |= (1 << ((cpu) % 8))) which is more convenient to process later on in the script. Signed-off-by: Daniel P. Berrangé <berrange@redhat.com> --- scripts/apibuild.py | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/scripts/apibuild.py b/scripts/apibuild.py index b13b5db644..68c588d8b6 100755 --- a/scripts/apibuild.py +++ b/scripts/apibuild.py @@ -494,6 +494,28 @@ class CLexer: if self.tokens[0][1] == "#": self.tokens[0] = ('preproc', "#" + self.tokens[1][1]) del self.tokens[1] + + if self.tokens[0][1] == "#define" and "(" in self.tokens[1][1]: + newtokens = [self.tokens[0]] + + endArg = self.tokens[1][1].find(")") + if endArg != -1: + extra = self.tokens[1][1][endArg+1:] + name = self.tokens[1][1][0:endArg+1] + newtokens.append(('preproc', name)) + if extra != "": + newtokens.append(('preproc', extra)) + else: + name = self.tokens[1][1] + for token in self.tokens[2:]: + if name is not None: + name = name + token[1] + if ")" in token[1]: + newtokens.append(('preproc', name)) + name = None + else: + newtokens.append(token) + self.tokens = newtokens break nline = len(line) if line[0] == '"' or line[0] == "'": -- 2.26.2
Currently the information about enums in the API document lacks any mention of parameters, so it is impossible to tell what kind of enum declaration is present in the libvirt API header. With this change <macro name='LIBVIR_CHECK_VERSION' file='libvirt-common'> <macro name='VIR_COPY_CPUMAP' file='libvirt-domain'> ...snip... becomes <macro name='LIBVIR_CHECK_VERSION' file='libvirt-common' params='major,minor,micro'> <macro name='VIR_COPY_CPUMAP' file='libvirt-domain' params='cpumaps,maplen,vcpu,cpumap'> ...snip... Signed-off-by: Daniel P. Berrangé <berrange@redhat.com> --- scripts/apibuild.py | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/scripts/apibuild.py b/scripts/apibuild.py index 68c588d8b6..9faf15a75e 100755 --- a/scripts/apibuild.py +++ b/scripts/apibuild.py @@ -1013,10 +1013,12 @@ class CParser: token[1][0] != '#'): lst.append(token[1]) token = self.lexer.token() - try: - name = name.split('(')[0] - except Exception: - pass + + paramStart = name.find("(") + params = None + if paramStart != -1: + params = name[paramStart+1:-1] + name = name[0:paramStart] # skip hidden macros if name in hidden_macros: @@ -1029,7 +1031,7 @@ class CParser: strValue = lst[0][1:-1] (args, desc) = self.parseMacroComment(name, not self.is_header) self.index_add(name, self.filename, not self.is_header, - "macro", (args, desc, strValue)) + "macro", (args, desc, params, strValue)) return token # @@ -2174,10 +2176,13 @@ class docBuilder: if id.info is None: args = [] desc = None + params = None strValue = None else: - (args, desc, strValue) = id.info + (args, desc, params, strValue) = id.info + if params is not None: + output.write(" params='%s'" % params) if strValue is not None: output.write(" string='%s'" % strValue) output.write(">\n") -- 2.26.2
Currently the value for an enum is only emitted if it is a plain string. If the enum is an integer or hex value, or a complex code block, it is omitted from the API build. This fixes that by emitting the raw value if no string value is present. With this change: <macro name='LIBVIR_CHECK_VERSION' file='libvirt-common' params='major,minor,micro'> <macro name='LIBVIR_VERSION_NUMBER' file='libvirt-common'> <macro name='VIR_COPY_CPUMAP' file='libvirt-domain' params='cpumaps,maplen,vcpu,cpumap'> ...snip... <macro name='LIBVIR_CHECK_VERSION' file='libvirt-common' params='major,minor,micro' raw='((major) * 1000000 + (minor) * 1000 + (micro) <= LIBVIR_VERSION_NUMBER)'> <macro name='LIBVIR_VERSION_NUMBER' file='libvirt-common' raw='6004000'> <macro name='VIR_COPY_CPUMAP' file='libvirt-domain' params='cpumaps,maplen,vcpu,cpumap' raw='memcpy(cpumap, VIR_GET_CPUMAP(cpumaps, maplen, vcpu), maplen)'> ...snip... Signed-off-by: Daniel P. Berrangé <berrange@redhat.com> --- scripts/apibuild.py | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/scripts/apibuild.py b/scripts/apibuild.py index 9faf15a75e..d63489ba62 100755 --- a/scripts/apibuild.py +++ b/scripts/apibuild.py @@ -1027,11 +1027,14 @@ class CParser: return token strValue = None + rawValue = None if len(lst) == 1 and lst[0][0] == '"' and lst[0][-1] == '"': strValue = lst[0][1:-1] + else: + rawValue = " ".join(lst) (args, desc) = self.parseMacroComment(name, not self.is_header) self.index_add(name, self.filename, not self.is_header, - "macro", (args, desc, params, strValue)) + "macro", (args, desc, params, strValue, rawValue)) return token # @@ -2178,13 +2181,16 @@ class docBuilder: desc = None params = None strValue = None + rawValue = None else: - (args, desc, params, strValue) = id.info + (args, desc, params, strValue, rawValue) = id.info if params is not None: output.write(" params='%s'" % params) if strValue is not None: output.write(" string='%s'" % strValue) + else: + output.write(" raw='%s'" % rawValue) output.write(">\n") if desc is not None and desc != "": -- 2.26.2
On 5/19/20 3:01 PM, Daniel P. Berrangé wrote:
Currently the value for an enum is only emitted if it is a plain string. If the enum is an integer or hex value, or a complex code block, it is omitted from the API build. This fixes that by emitting the raw value if no string value is present.
With this change:
<macro name='LIBVIR_CHECK_VERSION' file='libvirt-common' params='major,minor,micro'> <macro name='LIBVIR_VERSION_NUMBER' file='libvirt-common'> <macro name='VIR_COPY_CPUMAP' file='libvirt-domain' params='cpumaps,maplen,vcpu,cpumap'> ...snip...
<macro name='LIBVIR_CHECK_VERSION' file='libvirt-common' params='major,minor,micro' raw='((major) * 1000000 + (minor) * 1000 + (micro) <= LIBVIR_VERSION_NUMBER)'> <macro name='LIBVIR_VERSION_NUMBER' file='libvirt-common' raw='6004000'> <macro name='VIR_COPY_CPUMAP' file='libvirt-domain' params='cpumaps,maplen,vcpu,cpumap' raw='memcpy(cpumap, VIR_GET_CPUMAP(cpumaps, maplen, vcpu), maplen)'> ...snip...
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com> --- scripts/apibuild.py | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-)
I'm seeing some weird errors after I apply this one, like: make[2]: Entering directory '/home/zippy/work/libvirt/libvirt.git/_build/docs' /usr/bin/xsltproc --nonet -o ./ \ --stringparam builddir '/home/zippy/work/libvirt/libvirt.git/_build' \ --stringparam timestamp "Thu May 21 12:42:53 UTC 2020" \ ../../docs/newapi.xsl libvirt-api.xml libvirt-api.xml:2092: parser error : Unescaped '<' not allowed in attributes values ' params='major,minor,micro' raw='((major) * 1000000 + (minor) * 1000 + (micro) ^ libvirt-api.xml:2092: parser error : attributes construct error ' params='major,minor,micro' raw='((major) * 1000000 + (minor) * 1000 + (micro) ^ libvirt-api.xml:2092: parser error : Couldn't find end of Start Tag macro line 2092 ' params='major,minor,micro' raw='((major) * 1000000 + (minor) * 1000 + (micro) ^ libvirt-api.xml:2092: parser error : StartTag: invalid element name params='major,minor,micro' raw='((major) * 1000000 + (minor) * 1000 + (micro) < ^ libvirt-api.xml:2097: parser error : Opening and ending tag mismatch: symbols line 2091 and macro </macro> ^ libvirt-api.xml:2146: parser error : xmlParseEntityRef: no name _CPU_USED' file='libvirt-domain' params='cpumap,cpu' raw='((cpumap)[(cpu) / 8] & ^ libvirt-api.xml:2146: parser error : Unescaped '<' not allowed in attributes values _USED' file='libvirt-domain' params='cpumap,cpu' raw='((cpumap)[(cpu) / 8] & (1 ^ libvirt-api.xml:2146: parser error : attributes construct error _USED' file='libvirt-domain' params='cpumap,cpu' raw='((cpumap)[(cpu) / 8] & (1 ^ libvirt-api.xml:2146: parser error : Couldn't find end of Start Tag macro line 2146 _USED' file='libvirt-domain' params='cpumap,cpu' raw='((cpumap)[(cpu) / 8] & (1 ^ libvirt-api.xml:2146: parser error : StartTag: invalid element name USED' file='libvirt-domain' params='cpumap,cpu' raw='((cpumap)[(cpu) / 8] & (1 < ^ libvirt-api.xml:2146: parser error : StartTag: invalid element name SED' file='libvirt-domain' params='cpumap,cpu' raw='((cpumap)[(cpu) / 8] & (1 << ^ libvirt-api.xml:2150: parser error : Opening and ending tag mismatch: api line 2 and macro </macro> ^ libvirt-api.xml:2151: parser error : Extra content at the end of the document <macro name='VIR_DOMAIN_BANDWIDTH_IN_AVERAGE' file='libvirt-domain' string=' ^ unable to parse libvirt-api.xml Michal
On Thu, May 21, 2020 at 02:43:10PM +0200, Michal Privoznik wrote:
On 5/19/20 3:01 PM, Daniel P. Berrangé wrote:
Currently the value for an enum is only emitted if it is a plain string. If the enum is an integer or hex value, or a complex code block, it is omitted from the API build. This fixes that by emitting the raw value if no string value is present.
With this change:
<macro name='LIBVIR_CHECK_VERSION' file='libvirt-common' params='major,minor,micro'> <macro name='LIBVIR_VERSION_NUMBER' file='libvirt-common'> <macro name='VIR_COPY_CPUMAP' file='libvirt-domain' params='cpumaps,maplen,vcpu,cpumap'> ...snip...
<macro name='LIBVIR_CHECK_VERSION' file='libvirt-common' params='major,minor,micro' raw='((major) * 1000000 + (minor) * 1000 + (micro) <= LIBVIR_VERSION_NUMBER)'> <macro name='LIBVIR_VERSION_NUMBER' file='libvirt-common' raw='6004000'> <macro name='VIR_COPY_CPUMAP' file='libvirt-domain' params='cpumaps,maplen,vcpu,cpumap' raw='memcpy(cpumap, VIR_GET_CPUMAP(cpumaps, maplen, vcpu), maplen)'> ...snip...
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com> --- scripts/apibuild.py | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-)
I'm seeing some weird errors after I apply this one, like:
Sigh, the patch i sent was missing the "escape()" call to escape <>" 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 :|
On 5/21/20 2:47 PM, Daniel P. Berrangé wrote:
Sigh, the patch i sent was missing the "escape()" call to escape <>"
That's okay. Just send a diff you squash in before pushing so that I can ACK these. Michal
On Tue, May 19, 2020 at 02:01:19PM +0100, Daniel P. Berrangé wrote:
Currently the value for an enum is only emitted if it is a plain string. If the enum is an integer or hex value, or a complex code block, it is omitted from the API build. This fixes that by emitting the raw value if no string value is present.
With this change:
<macro name='LIBVIR_CHECK_VERSION' file='libvirt-common' params='major,minor,micro'> <macro name='LIBVIR_VERSION_NUMBER' file='libvirt-common'> <macro name='VIR_COPY_CPUMAP' file='libvirt-domain' params='cpumaps,maplen,vcpu,cpumap'> ...snip...
<macro name='LIBVIR_CHECK_VERSION' file='libvirt-common' params='major,minor,micro' raw='((major) * 1000000 + (minor) * 1000 + (micro) <= LIBVIR_VERSION_NUMBER)'> <macro name='LIBVIR_VERSION_NUMBER' file='libvirt-common' raw='6004000'> <macro name='VIR_COPY_CPUMAP' file='libvirt-domain' params='cpumaps,maplen,vcpu,cpumap' raw='memcpy(cpumap, VIR_GET_CPUMAP(cpumaps, maplen, vcpu), maplen)'> ...snip...
Signed-off-by: Daniel P. Berrangé <berrange@redhat.com> --- scripts/apibuild.py | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-)
diff --git a/scripts/apibuild.py b/scripts/apibuild.py index 9faf15a75e..d63489ba62 100755 --- a/scripts/apibuild.py +++ b/scripts/apibuild.py @@ -1027,11 +1027,14 @@ class CParser: return token
strValue = None + rawValue = None if len(lst) == 1 and lst[0][0] == '"' and lst[0][-1] == '"': strValue = lst[0][1:-1] + else: + rawValue = " ".join(lst) (args, desc) = self.parseMacroComment(name, not self.is_header) self.index_add(name, self.filename, not self.is_header, - "macro", (args, desc, params, strValue)) + "macro", (args, desc, params, strValue, rawValue)) return token
# @@ -2178,13 +2181,16 @@ class docBuilder: desc = None params = None strValue = None + rawValue = None else: - (args, desc, params, strValue) = id.info + (args, desc, params, strValue, rawValue) = id.info
if params is not None: output.write(" params='%s'" % params) if strValue is not None: output.write(" string='%s'" % strValue) + else: + output.write(" raw='%s'" % rawValue) output.write(">\n")
if desc is not None and desc != "":
This last chunk needs to be if strValue is not None: output.write(" string='%s'" % strValue) + else: + output.write(" raw='%s'" % escape(rawValue)) output.write(">\n") if desc is not None and desc != "": 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 :|
participants (2)
-
Daniel P. Berrangé -
Michal Privoznik