[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]] <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]] </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]] </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.]] <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.]] <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.]] <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 ','.]] </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.]] </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.]] </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().]] </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]] </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()]] </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.]] </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.]] </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.]]= </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"]] </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.]] </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.]] </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.]] </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.]] </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.]] <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.]] </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.]] </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()]] </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.]] </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.]] <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.]] </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()]] </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.]] </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]= ] </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.]] </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()]] </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.]] </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.]= ] </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.]] </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()]] </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]] </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= .]] <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()]] </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()]] </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