This document walks you through the process of implementing a new - API in libvirt. It uses as an example the addition of an API for - separating maximum from current vcpu usage of a domain, over - the course of a fifteen-patch series. - Remember that new API consists of any new public functions, as - well as the addition of flags or extensions of XML used by - existing functions. The example in this document adds both new - functions and an XML extension. Not all libvirt API additions - require quite as many patches. + API in libvirt. Remember that new API consists of any new public + functions, as well as the addition of flags or extensions of XML used by + existing functions.
@@ -27,12 +22,7 @@ added to libvirt. Someone may already be working on the feature you want. Also, recognize that everything you write is likely to undergo significant rework as you discuss it with the other developers, so - don't wait too long before getting feedback. In the vcpu example - below, list feedback was first requested - here - and resulted in several rounds of improvements before coding - began. In turn, this example is slightly rearranged from the actual - order of the commits. + don't wait too long before getting feedback.
@@ -81,14 +71,13 @@
- Submit new code in the form shown in the example code: one patch - per step. That's not to say submit patches before you have working - functionality--get the whole thing working and make sure you're happy - with it. Then use git or some other version control system that lets - you rewrite your commit history and break patches into pieces so you - don't drop a big blob of code on the mailing list in one go. - Also, you should follow the upstream tree, and rebase your - series to adapt your patches to work with any other changes + Submit new code in the form of one patch per step. That's not to say + submit patches before you have working functionality--get the whole thing + working and make sure you're happy with it. Then use git or some other + version control system that lets you rewrite your commit history and + break patches into pieces so you don't drop a big blob of code on the + mailing list in one go. Also, you should follow the upstream tree, and + rebase your series to adapt your patches to work with any other changes that were accepted upstream during your development.
@@ -101,8 +90,6 @@ separately. -With that said, let's begin.
-The first task is to define the public API. If the new API @@ -133,10 +120,6 @@ rework it as you go through the process of implementing it.
-See 0001-add-to-xml.patch - and 0002-add-new-public-API.patch - for example code.
-
@@ -164,8 +147,6 @@
provide a NULL stub for the new function.
See 0003-define-internal-driver-API.patch
-@@ -199,20 +180,14 @@
src/libvirt.c
See 0004-implement-the-public-APIs.patch
-Implementing the remote protocol is essentially a straightforward exercise which is probably most easily - understood by referring to the existing code and the example - patch. It involves several related changes, including the - regeneration of derived files, with further details below. + understood by referring to the existing code.
-See 0005-implement-the-remote-protocol.patch
-@@ -298,8 +273,6 @@ existing lines probably imply a backwards-incompatible API change.
-See 0005-implement-the-remote-protocol.patch
-@@ -312,8 +285,6 @@ not necessary if the new API has no relation to existing API.
-See 0006-make-old-API-trivially-wrap-to-new-API.patch
-@@ -343,8 +314,6 @@ tools/virsh.pod
-See 0007-add-virsh-support.patch
-@@ -371,8 +340,6 @@ the same way as the older API wrappers.
-See 0008-support-new-xml.patch
-@@ -384,41 +351,14 @@
- In the example patches, three separate drivers are supported: - test, qemu, and xen. It is always a good idea to patch the test - driver in addition to the target driver, to prove that the API - can be used for more than one driver. The example updates the - test driver in one patch: + It is always a good idea to patch the test driver in addition to the + target driver, to prove that the API can be used for more than one + driver.
-See 0009-support-all-flags-in-test-driver.patch
-- The qemu changes were easier to split into two phases, one for - updating the mapping between the new XML and the hypervisor - command line arguments, and one for supporting all possible - flags of the new API: -
- -See 0010-improve-vcpu-support-in-qemu-command-line.patch - and 0011-complete-vcpu-support-in-qemu-driver.patch
- -- Finally, the example breaks the xen driver changes across four - patches. One maps the XML changes to the hypervisor command, - the next two are independently implementing the getter and - setter APIs, and the last one provides cleanup of code that was - rendered dead by the new API. -
- -See 0012-improve-vcpu-support-in-xen-command-line.patch, - 0013-improve-getting-xen-vcpu-counts.patch, - 0014-improve-setting-xen-vcpu-counts.patch, - and 0015-remove-dead-xen-code.patch
- -- The exact details of the example code are probably uninteresting - unless you're concerned with virtual cpu management. + Any cleanups resulting from the changes should be added as separate + patches at the end of the series.