- Devel - libvirt List Archives

[libvirt] [PATCH perl v2] Add constants for new perf event support
by Nitesh Konkar 07 Mar '17

07 Mar '17

Signed-off-by: Nitesh Konkar <nitkon12(a)linux.vnet.ibm.com> --- Changes | 9 +++++++++ Virt.xs | 9 +++++++++ lib/Sys/Virt/Domain.pm | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 72 insertions(+) diff --git a/Changes b/Changes index 842f21f..7d637f5 100644 --- a/Changes +++ b/Changes @@ -5,6 +5,15 @@ Revision history for perl module Sys::Virt - Add VIR_CONNECT_LIST_STORAGE_POOLS_VSTORAGE constant - Add VIR_CONNECT_LIST_NODE_DEVICES_CAP_DRM constant - Add virDomainSetVcpu API + - Add PERF_PARAM_CPU_CLOCK constant + - Add PERF_PARAM_TASK_CLOCK constant + - Add PERF_PARAM_PAGE_FAULTS constant + - Add PERF_PARAM_CONTEXT_SWITCHES constant + - Add PERF_PARAM_CPU_MIGRATIONS constant + - Add PERF_PARAM_PAGE_FAULTS_MIN constant + - Add PERF_PARAM_PAGE_FAULTS_MAJ constant + - Add PERF_PARAM_ALIGNMENT_FAULTS constant + - Add PERF_PARAM_EMULATION_FAULTS constant 3.0.0 2017-01-19 diff --git a/Virt.xs b/Virt.xs index 9728fb0..e80182f 100644 --- a/Virt.xs +++ b/Virt.xs @@ -8500,6 +8500,15 @@ BOOT: REGISTER_CONSTANT_STR(VIR_PERF_PARAM_STALLED_CYCLES_FRONTEND, PERF_PARAM_STALLED_CYCLES_FRONTEND); REGISTER_CONSTANT_STR(VIR_PERF_PARAM_STALLED_CYCLES_BACKEND, PERF_PARAM_STALLED_CYCLES_BACKEND); REGISTER_CONSTANT_STR(VIR_PERF_PARAM_REF_CPU_CYCLES, PERF_PARAM_REF_CPU_CYCLES); + REGISTER_CONSTANT_STR(VIR_PERF_PARAM_CPU_CLOCK, PERF_PARAM_CPU_CLOCK); + REGISTER_CONSTANT_STR(VIR_PERF_PARAM_TASK_CLOCK, PERF_PARAM_TASK_CLOCK); + REGISTER_CONSTANT_STR(VIR_PERF_PARAM_PAGE_FAULTS, PERF_PARAM_PAGE_FAULTS); + REGISTER_CONSTANT_STR(VIR_PERF_PARAM_CONTEXT_SWITCHES, PERF_PARAM_CONTEXT_SWITCHES); + REGISTER_CONSTANT_STR(VIR_PERF_PARAM_CPU_MIGRATIONS, PERF_PARAM_CPU_MIGRATIONS); + REGISTER_CONSTANT_STR(VIR_PERF_PARAM_PAGE_FAULTS_MIN, PERF_PARAM_PAGE_FAULTS_MIN); + REGISTER_CONSTANT_STR(VIR_PERF_PARAM_PAGE_FAULTS_MAJ, PERF_PARAM_PAGE_FAULTS_MAJ); + REGISTER_CONSTANT_STR(VIR_PERF_PARAM_ALIGNMENT_FAULTS, PERF_PARAM_ALIGNMENT_FAULTS); + REGISTER_CONSTANT_STR(VIR_PERF_PARAM_EMULATION_FAULTS, PERF_PARAM_EMULATION_FAULTS); REGISTER_CONSTANT_STR(VIR_DOMAIN_BANDWIDTH_IN_AVERAGE, BANDWIDTH_IN_AVERAGE); REGISTER_CONSTANT_STR(VIR_DOMAIN_BANDWIDTH_IN_PEAK, BANDWIDTH_IN_PEAK); diff --git a/lib/Sys/Virt/Domain.pm b/lib/Sys/Virt/Domain.pm index 6b36e73..eea8b26 100644 --- a/lib/Sys/Virt/Domain.pm +++ b/lib/Sys/Virt/Domain.pm @@ -2814,6 +2814,60 @@ frequency scaling by applications running on the platform. It corresponds to the "perf.ref_cpu_cycles" field in the *Stats APIs. +=item Sys::Virt::Domain::PERF_PARAM_CPU_CLOCK +The cpu_clock perf event counter which can be used to +measure the count of cpu clock time by applications +running on the platform. It corresponds to the +"perf.cpu_clock" field in the *Stats APIs. + +=item Sys::Virt::Domain::PERF_PARAM_TASK_CLOCK +The task_clock perf event counter which can be used to +measure the count of task clock time by applications +running on the platform. It corresponds to the +"perf.task_clock" field in the *Stats APIs. + +=item Sys::Virt::Domain::PERF_PARAM_PAGE_FAULTS +The page_faults perf event counter which can be used to +measure the count of page faults by applications running +on the platform. It corresponds to the "perf.page_faults" +field in the *Stats APIs. + +=item Sys::Virt::Domain::PERF_PARAM_CONTEXT_SWITCHES +The context_switches perf event counter which can be used to +measure the count of context switches by applications running +on the platform. It corresponds to the "perf.context_switches" +field in the *Stats APIs. + +=item Sys::Virt::Domain::PERF_PARAM_CPU_MIGRATIONS +The cpu_migrations perf event counter which can be used to +measure the count of cpu migrations by applications running +on the platform. It corresponds to the "perf.cpu_migrations" +field in the *Stats APIs. + +=item Sys::Virt::Domain::PERF_PARAM_PAGE_FAULTS_MIN +The page_faults_min perf event counter which can be used to +measure the count of minor page faults by applications running +on the platform. It corresponds to the "perf.page_faults_min" +field in the *Stats APIs. + +=item Sys::Virt::Domain::PERF_PARAM_PAGE_FAULTS_MAJ +The page_faults_maj perf event counter which can be used to +measure the count of major page faults by applications running +on the platform. It corresponds to the "perf.page_faults_maj" +field in the *Stats APIs. + +=item Sys::Virt::Domain::PERF_PARAM_ALIGNMENT_FAULTS +The alignment_faults perf event counter which can be used to +measure the count of alignment faults by applications running +on the platform. It corresponds to the "perf.alignment_faults" +field in the *Stats APIs. + +=item Sys::Virt::Domain::PERF_PARAM_EMULATION_FAULTS +The emulation_faults perf event counter which can be used to +measure the count of emulation faults by applications running +on the platform. It corresponds to the "perf.emulation_faults" +field in the *Stats APIs. + =back =head2 VCPU FLAGS -- 1.9.3

2 2

[libvirt] [PATCH 0/6] Split out nwfilter object into its own module
by John Ferlan 07 Mar '17

07 Mar '17

Continuing down the pile of drivers from my RFC for making a common pool object - we're now at nwfilter (still have storage and network to go). For reference see patch 3 of: http://www.redhat.com/archives/libvir-list/2017-February/msg00519.html This series works through the nwfilter conf adjustments. We start by fixing a couple of API's that aren't using objects, then launch into the repetitive type actions of moving the code into it's own module, fixing up the "style", altering the function prototypes, and finally using virNWFilterObj prefix for any API's in virnwfilterobj. John Ferlan (6): conf: Change virNWFilterObjSaveDef to virNWFilterSaveDef conf: Change virNWFilterObjDeleteDef to virNWFilterDeleteDef conf: Introduce virnwfilterobj conf: Adjust coding style for nwfilter conf sources conf: Alter coding style of nwfilter function prototypes conf: Use consistent function name prefixes for virnwfilterobj po/POTFILES.in | 1 + src/Makefile.am | 6 +- src/conf/nwfilter_conf.c | 498 +++++++-------------------------- src/conf/nwfilter_conf.h | 157 +++++------ src/conf/virnwfilterobj.c | 388 +++++++++++++++++++++++++ src/conf/virnwfilterobj.h | 94 +++++++ src/libvirt_private.syms | 26 +- src/nwfilter/nwfilter_driver.c | 13 +- src/nwfilter/nwfilter_gentech_driver.h | 2 +- src/nwfilter/nwfilter_tech_driver.h | 2 +- 10 files changed, 676 insertions(+), 511 deletions(-) create mode 100644 src/conf/virnwfilterobj.c create mode 100644 src/conf/virnwfilterobj.h -- 2.9.3

2 9

[libvirt] [PATCH 0/3] use USB nec-usb-xhci controller as default if possible for ppc64
by Pavel Hrdina 07 Mar '17

07 Mar '17

Pavel Hrdina (3): qemu_domain: move controller post parse code into its own function qemu_domain: cleanup the controller post parse code qemu_domain: use correct default USB controller on ppc64 src/qemu/qemu_domain.c | 218 +++++++++++++++++++++++++++---------------------- 1 file changed, 120 insertions(+), 98 deletions(-) -- 2.12.0

3 14

[libvirt] [PATCH] storage: Don't pass 'iso' format to qemu-img
by Cole Robinson 07 Mar '17

07 Mar '17

$ virsh vol-clone /tmp/test.iso new.iso error: Failed to clone vol from test.iso error: internal error: Child process (/bin/qemu-img convert -f iso -O iso /tmp/test.iso /tmp/new.iso) unexpected exit status 1: qemu-img: Could not open '/tmp/test.iso': Unknown driver 'iso' Map iso->raw before sending the format value to qemu-img https://bugzilla.redhat.com/show_bug.cgi?id=972784 https://bugzilla.redhat.com/show_bug.cgi?id=1419395 --- src/storage/storage_util.c | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/storage/storage_util.c b/src/storage/storage_util.c index 41253b9..bf6f0b3 100644 --- a/src/storage/storage_util.c +++ b/src/storage/storage_util.c @@ -1009,6 +1009,8 @@ storageBackendCreateQemuImgSetInput(virStorageVolDefPtr inputvol, info->inputFormat = inputvol->target.format; if (inputvol->type == VIR_STORAGE_VOL_BLOCK) info->inputFormat = VIR_STORAGE_FILE_RAW; + if (info->inputFormat == VIR_STORAGE_FILE_ISO) + info->inputFormat = VIR_STORAGE_FILE_RAW; if (!(info->inputFormatStr = virStorageFileFormatTypeToString(info->inputFormat))) { virReportError(VIR_ERR_INTERNAL_ERROR, @@ -1175,6 +1177,9 @@ virStorageBackendCreateQemuImgCmdFromVol(virConnectPtr conn, if (vol->type == VIR_STORAGE_VOL_BLOCK) info.format = VIR_STORAGE_FILE_RAW; + if (info.format == VIR_STORAGE_FILE_ISO) + info.format = VIR_STORAGE_FILE_RAW; + if (!(type = virStorageFileFormatTypeToString(info.format))) { virReportError(VIR_ERR_INTERNAL_ERROR, _("unknown storage vol type %d"), -- 2.9.3

3 3

[libvirt] [PATCH 0/2] Fix a couple of Coverity found issues from recent patches
by John Ferlan 07 Mar '17

07 Mar '17

The virsysinfo changes caused Coverity to "take another look" at the code and it found some issues. Each is described in the patch commit. John Ferlan (2): util: Resource some resource leaks in virsysinfo code util: Avoid possible NULL dereference in virSysinfoParsePPCProcessor src/util/virsysinfo.c | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) -- 2.9.3

2 3

[libvirt] [PATCH 0/4] Refactor and fix sysinfo data retrieval and the testing of the code
by Peter Krempa 07 Mar '17

07 Mar '17

src/util/virsysinfo.c was a big mess of conditionally compiled functions with the same name for each platform. Also the test was run only for the current platform. Remove the churn and make all tests run on all platforms since there is no platform dependency. Peter Krempa (4): util: sysinfo: Reduce amount of conditionally compiled code tests: sysinfo: Export virSysinfoSetup via the private header tests: sysinfo: Run all sysinfo tests all the time tests: sysinfo: Add test data for HP moonshot aarch64 box src/Makefile.am | 2 +- src/libvirt_private.syms | 7 + src/util/virsysinfo.c | 172 ++++++++++++----------- src/util/virsysinfopriv.h | 44 ++++++ tests/sysinfodata/aarch64-moonshotcpuinfo.data | 72 ++++++++++ tests/sysinfodata/aarch64-moonshotsysinfo.expect | 1 + tests/sysinfotest.c | 115 ++++----------- 7 files changed, 241 insertions(+), 172 deletions(-) create mode 100644 src/util/virsysinfopriv.h create mode 100644 tests/sysinfodata/aarch64-moonshotcpuinfo.data create mode 100644 tests/sysinfodata/aarch64-moonshotsysinfo.expect -- 2.11.0

2 6

[libvirt] [PATCH] libvirt: document UNDEFINE_KEEP_NVRAM in UndefineFlags docs
by Cole Robinson 07 Mar '17

07 Mar '17

--- src/libvirt-domain.c | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/libvirt-domain.c b/src/libvirt-domain.c index 619a9fc..749297f 100644 --- a/src/libvirt-domain.c +++ b/src/libvirt-domain.c @@ -6287,9 +6287,9 @@ virDomainUndefine(virDomainPtr domain) * whether this flag is present. On hypervisors where snapshots do * not use libvirt metadata, this flag has no effect. * - * If the domain has any nvram specified, then including - * VIR_DOMAIN_UNDEFINE_NVRAM will also remove that file, and omitting the flag - * will cause the undefine process to fail. + * If the domain has any nvram specified, the undefine process will fail + * unless VIR_DOMAIN_UNDEFINE_KEEP_NVRAM is specified, or if + * VIR_DOMAIN_UNDEFINE_NVRAM is specified to remove the nvram file. * * Returns 0 in case of success, -1 in case of error */ -- 2.9.3

2 1

[libvirt] [PATH V10 00/12] Support cache tune in libvirt
by Eli Qiao 07 Mar '17

07 Mar '17

Addressed comment from v9 -> v8 Marcelo: * Improve default schemata calculate, support allocate from low schemata bits for other APP. Addressed comment from v9 -> v8 Marcelo: * New public API to query cache usage Eli: * Fix core dump while multiple tasks are added. Addressed comment from v8 -> v7 Martin: * Patch subject prefix. * Move some of cpu related information to virhostcpu.c. * Fix some memory leak in src/utils/resctrl.c Martin & Marcelo: * Don't remove directories which are not maintained by libvirt. Addressed comment from v7 -> v6 Marcelo: * Fix flock usage while VM initialization. Addressed comment from v6 -> v5 Marcelo: * Support other APPs to operate /sys/fs/resctrl at same time Libvirt will scan /sys/fs/resctrl again before doing cache allocation. patch 10 will address this. Addressed comment from v4 -> v5: Marcelo: * Several typos * Use flock instead of virFileLock Addressed comment from v3 -> v4: Daniel & Marcelo: * Added concurrence support Addressed comment from v2 -> v3: Daniel: * Fixed coding style, passed `make check` and `make syntax-check` * Variables renaming and move from header file to c file. * For locking/mutex support, no progress. There are some discussion from mailing list, but I can not find a better way to add locking support without performance impact. I'll explain the process and please help to advice what shoud we do. VM create: 1) Get the cache left value on each bank of the host. This should be shared amount all VMs. 2) Calculate the schemata on the bank based on all created resctrl domain's schemata 3) Calculate the default schemata by scaning all domain's schemata. 4) Flush default schemata to /sys/fs/resctrl/schemata VM destroy: 1) Remove the resctrl domain of that VM 2) Recalculate default schemata 3) Flush default schemata to /sys/fs/resctrl/schemata The key point is that all VMs shares /sys/fs/resctrl/schemata, and when a VM create a resctrl domain, the schemata of that VM depends on the default schemata and all other exsited schematas. So a global mutex is reqired. Before calculate a schemata or update default schemata, libvirt should gain this global mutex. I will try to think more about how to support this gracefully in next patch set. Marcelo: * Added vcpu support for cachetune, this will allow user to define which vcpu using which cache allocation bank. <cachetune id='0' host_id=0 size='3072' unit='KiB' vcpus='0,1'/> vcpus is a cpumap, the vcpu pids will be added to tasks file * Added cdp compatible, user can specify l3 cache even host enable cdp. See patch 8. On a cdp enabled host, specify l3code/l3data by <cachetune id='0' host_id='0' type='l3' size='3072' unit='KiB'/> This will create a schemata like: L3data:0=0xff00;... L3code:0=0xff00;... * Would you please help to test if the functions work. Martin: * Xml test case, I have no time to work on this yet, would you please show me an example, would like to amend it later. This series patches are for supportting CAT featues, which also called cache tune in libvirt. First to expose cache information which could be tuned in capabilites XML. Then add new domain xml element support to add cacahe bank which will apply on this libvirt domain. This series patches add a util file `resctrl.c/h`, an interface to talk with linux kernel's system fs. There are still one TODO left: 1. Expose a new public interface to get free cache information. 2. Expose a new public interface to set cachetune lively. Some discussion about this feature support can be found from: https://www.redhat.com/archives/libvir-list/2017-January/msg00644.html Eli Qiao (12): Resctrl: Add some utils functions Resctrl: expose cache information to capabilities Resctrl: Add new xml element to support cache tune Resctrl: Add private interfaces to operate cache bank Qemu: Set cache tune while booting a new domain. Resctrl: enable l3code/l3data Resctrl: Make sure l3data/l3code are pairs Resctrl: Compatible mode for cdp enabled Resctrl: concurrence support Resctrl: Scan resctrl before doing cache allocation Resctrl: Add Public API for nodecachestats Resctrl: Add nodecachestats daemon/remote.c | 67 +++ docs/schemas/domaincommon.rng | 46 ++ include/libvirt/libvirt-host.h | 32 ++ include/libvirt/virterror.h | 1 + po/POTFILES.in | 1 + src/Makefile.am | 1 + src/conf/capabilities.c | 56 ++ src/conf/capabilities.h | 23 + src/conf/domain_conf.c | 182 +++++++ src/conf/domain_conf.h | 19 + src/driver-hypervisor.h | 7 + src/libvirt-host.c | 41 ++ src/libvirt_private.syms | 12 + src/libvirt_public.syms | 1 + src/nodeinfo.c | 64 +++ src/nodeinfo.h | 1 + src/qemu/qemu_capabilities.c | 8 + src/qemu/qemu_driver.c | 18 + src/qemu/qemu_process.c | 54 ++ src/remote/remote_driver.c | 52 ++ src/remote/remote_protocol.x | 25 +- src/remote_protocol-structs | 16 + src/util/virerror.c | 1 + src/util/virhostcpu.c | 186 ++++++- src/util/virhostcpu.h | 6 + src/util/virresctrl.c | 1098 ++++++++++++++++++++++++++++++++++++++++ src/util/virresctrl.h | 96 ++++ tools/virsh-host.c | 49 ++ 28 files changed, 2145 insertions(+), 18 deletions(-) create mode 100644 src/util/virresctrl.c create mode 100644 src/util/virresctrl.h -- 1.9.1

4 15

[libvirt] [PATCH] vz: correct error message
by Mikhail Feoktistov 06 Mar '17

06 Mar '17

--- src/vz/vz_sdk.c | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/vz/vz_sdk.c b/src/vz/vz_sdk.c index e16bb0c..84e89a5 100644 --- a/src/vz/vz_sdk.c +++ b/src/vz/vz_sdk.c @@ -2601,8 +2601,10 @@ prlsdkCheckUnsupportedParams(PRL_HANDLE sdkdom, virDomainDefPtr def) def->onCrash != VIR_DOMAIN_LIFECYCLE_CRASH_DESTROY) { virReportError(VIR_ERR_CONFIG_UNSUPPORTED, "%s", - _("on_reboot, on_poweroff and on_crash parameters " - "are not supported by vz driver")); + _("The following parameters must be " + "on_reboot = restart, on_poweroff = destroy, " + "on_crash = destroy. " + "Different actions are not supported by vz driver")); return -1; } -- 1.8.3.1

2 1

[libvirt] [PATCH] Document preferred naming conventions
by Daniel P. Berrange 06 Mar '17

06 Mar '17

This documents the preferred conventions for naming files, structs, enums, typedefs and functions. Signed-off-by: Daniel P. Berrange <berrange(a)redhat.com> --- HACKING | 71 ++++++++++++++++++++++++++++++++++++++++++++ docs/hacking.html.in | 83 ++++++++++++++++++++++++++++++++++++++++++++++++++++ docs/hacking2.xsl | 4 +++ 3 files changed, 158 insertions(+) diff --git a/HACKING b/HACKING index fff003b..16be5cf 100644 --- a/HACKING +++ b/HACKING @@ -239,6 +239,77 @@ on the subject, on Richard Jones' guide to working with open source projects <http://people.redhat.com/rjones/how-to-supply-code-to-open-source-projects/>. +Naming conventions +================== +When reading libvirt code, a number of different naming conventions will be +evident due to various changes in thinking over the course of the project's +lifetime. The conventions documented below should be followed when creating +any entirely new files in libvirt. When working on existing files, while it is +desirable to apply these conventions, keeping a consistent style with existing +code in that particular file is generally more important. The overall guiding +rule is that every file, enum, struct, function, and typedef name must have a +'vir' or 'VIR' prefix. All local scope variable names are exempt, and global +variables are exempt, unless exported in a header file. + +*File names* + +File naming varies depending on the subdirectory. The preferred style is to +have a 'vir' prefix, followed by a name which matches the name of the +functions / objects inside the file. For example, a file containing an object +'virHashtable' is stored in files 'virhashtable.c' and 'virhashtable.h'. +Sometimes, methods which would otherwise be declared 'static' need to be +exported for use by a test suite. For this purpose a second header file should +be added with a suffix of 'priv'. e.g. 'virhashtablepriv.h'. USe of +underscores in file names is discouraged when using the 'vir' prefix style. +The 'vir' prefix naming applies to src/util, src/rpc and tests/ directories. +Most other directories do not follow this convention. + + + +*Enum type & field names* + +All enums should have a 'vir' prefix in their typedef name, and each following +word should have its first letter in uppercase. The enum name should match the +typedef name with a leading underscore. The enum member names should be in all +uppercase, and use an underscore to separate each word. The enum member name +prefix should match the enum typedef name. + + typedef enum _virSocketType virSocketType; + enum _virSocketType { + VIR_SOCKET_TYPE_IPV4, + VIR_SOCKET_TYPE_IPV6, + }; + + +*Struct type names* + +All structs should have a 'vir' prefix in their typedef name, and each +following word should have its first letter in uppercase. The struct name +should be the same as the typedef name with a leading underscore. A second +typedef should be given for a pointer to the struct with a 'Ptr' suffix. + + typedef struct _virHashTable virHashTable; + typedef virHashTable *virHashTablePtr; + struct _virHashTable { + ... + }; + + +*Function names* + +All functions should have a 'vir' prefix in their name, followed by one or +more words with first letter of each word capitalized. Underscores should not +be used in function names. If the function is operating on an object, then the +function name prefix should match the object typedef name. For example, given +an object 'virHashTable', all functions should have a name 'virHashTableXXXX' +e.g. 'virHashTableLookup'. If there is no object associated with the function, +then its name prefix should match the filename. For example, given a filename +of 'virfile.h', all functions should have a name 'virFileXXXX' e.g. +'virFileTouch'. + + + + Code indentation ================ Libvirt's C source code generally adheres to some basic code-formatting diff --git a/docs/hacking.html.in b/docs/hacking.html.in index b1bb149..028536d 100644 --- a/docs/hacking.html.in +++ b/docs/hacking.html.in @@ -314,6 +314,89 @@ Richard Jones' guide to working with open source projects</a>. </p> + <h2><a name="naming">Naming conventions</a></h2> + + <p> + When reading libvirt code, a number of different naming conventions will + be evident due to various changes in thinking over the course of the + project's lifetime. The conventions documented below should be followed + when creating any entirely new files in libvirt. When working on existing + files, while it is desirable to apply these conventions, keeping a + consistent style with existing code in that particular file is generally + more important. The overall guiding rule is that every file, enum, struct, + function, and typedef name must have a 'vir' or 'VIR' prefix. All local + scope variable names are exempt, and global variables are exempt, unless + exported in a header file. + </p> + + <dl> + <dt>File names</dt> + <dd> + <p> + File naming varies depending on the subdirectory. The preferred + style is to have a 'vir' prefix, followed by a name which matches + the name of the functions / objects inside the file. For example, + a file containing an object 'virHashtable' is stored in files + 'virhashtable.c' and 'virhashtable.h'. Sometimes, methods which + would otherwise be declared 'static' need to be exported for use + by a test suite. For this purpose a second header file should be + added with a suffix of 'priv'. e.g. 'virhashtablepriv.h'. USe of + underscores in file names is discouraged when using the 'vir' + prefix style. The 'vir' prefix naming applies to src/util, + src/rpc and tests/ directories. Most other directories do not + follow this convention. + </p> + </dd> + <dt>Enum type & field names</dt> + <dd> + <p> + All enums should have a 'vir' prefix in their typedef name, + and each following word should have its first letter in + uppercase. The enum name should match the typedef name with + a leading underscore. The enum member names should be in all + uppercase, and use an underscore to separate each word. The + enum member name prefix should match the enum typedef name. + </p> + <pre> + typedef enum _virSocketType virSocketType; + enum _virSocketType { + VIR_SOCKET_TYPE_IPV4, + VIR_SOCKET_TYPE_IPV6, + };</pre> + </dd> + <dt>Struct type names</dt> + <dd> + <p> + All structs should have a 'vir' prefix in their typedef name, + and each following word should have its first letter in + uppercase. The struct name should be the same as the typedef + name with a leading underscore. A second typedef should be + given for a pointer to the struct with a 'Ptr' suffix. + </p> + <pre> + typedef struct _virHashTable virHashTable; + typedef virHashTable *virHashTablePtr; + struct _virHashTable { + ... + };</pre> + </dd> + <dt>Function names</dt> + <dd> + <p> + All functions should have a 'vir' prefix in their name, + followed by one or more words with first letter of each + word capitalized. Underscores should not be used in function + names. If the function is operating on an object, then the + function name prefix should match the object typedef name. + For example, given an object 'virHashTable', all functions + should have a name 'virHashTableXXXX' e.g. 'virHashTableLookup'. + If there is no object associated with the function, then its + name prefix should match the filename. For example, given a + filename of 'virfile.h', all functions should have a name + 'virFileXXXX' e.g. 'virFileTouch'. + </p> + </dd> + </dl> <h2><a name="indent">Code indentation</a></h2> <p> diff --git a/docs/hacking2.xsl b/docs/hacking2.xsl index 3595b7e..7e5ac82 100644 --- a/docs/hacking2.xsl +++ b/docs/hacking2.xsl @@ -114,6 +114,10 @@ from docs/hacking.html.in! <xsl:template match="html:li/html:ul/html:li">-- <xsl:apply-templates/><xsl:value-of select="$newline"/><xsl:value-of select="$newline"/> </xsl:template> +<xsl:template match="html:dl/html:dt">*<xsl:apply-templates/>*<xsl:value-of select="$newline"/><xsl:value-of select="$newline"/> +</xsl:template> +<xsl:template match="html:dl/html:dd"><xsl:apply-templates/><xsl:value-of select="$newline"/><xsl:value-of select="$newline"/> +</xsl:template>  -- 2.9.3

6 10