[libvirt] [PATCH 3/8] docs: document recent hook additions

[Eric Blake]

* src/qemu/qemu_process.c (qemuProcessStart, qemuProcessStop): Fix
typos.
* docs/hooks.html.in: Document 'prepare' and 'release' hooks.
---

Original post:
https://www.redhat.com/archives/libvir-list/2011-March/msg01112.html

 docs/hooks.html.in      |   23 +++++++++++++++++++----
 src/qemu/qemu_process.c |    4 ++--
 2 files changed, 21 insertions(+), 6 deletions(-)

diff --git a/docs/hooks.html.in b/docs/hooks.html.in
index 3503f8c..eec7a6a 100644
--- a/docs/hooks.html.in
+++ b/docs/hooks.html.in
@@ -100,11 +100,26 @@

     <h5><a name="qemu">/etc/libvirt/hooks/qemu</a></h5>
     <ul>
-      <li>When a QEMU guest is started, the qemu hook script is called as:<br/>
-          <pre>/etc/libvirt/hooks/qemu guest_name start begin -</pre></li>
+      <li>Before a QEMU guest is started, the qemu hook script is
+        called in two locations; if either location fails, the guest
+        is not started.  The first location, <span class="since">since
+        0.9.0</span>, is before libvirt performs any resource
+        labeling, and the hook can allocate resources not managed by
+        libvirt such as DRBD or missing bridges.  This is called as:</br>
+        <pre>/etc/libvirt/hooks/qemu guest_name prepare begin -</pre>
+        The second location, available <span class="since">Since
+        0.8.0</span>, occurs after libvirt has finished labeling
+        all resources, but has not yet started the guest, called as:</br>
+        <pre>/etc/libvirt/hooks/qemu guest_name start begin -</pre></li>
       <li>When a QEMU guest is stopped, the qemu hook script is called
-          as:<br/>
-          <pre>/etc/libvirt/hooks/qemu guest_name stopped end -</pre></li>
+        in two locations, to match the startup.
+        First, <span class="since">since 0.8.0</span>, the hook is
+        called before libvirt restores any labels:</br>
+        <pre>/etc/libvirt/hooks/qemu guest_name stopped end -</pre>
+        Then, after libvirt has released all resources, the hook is
+        called again, <span class="since">since 0.9.0</span>, to allow
+        any additional resource cleanup:<br/>
+        <pre>/etc/libvirt/hooks/qemu guest_name release end -</pre></li>
     </ul>

     <h5><a name="lxc">/etc/libvirt/hooks/lxc</a></h5>
diff --git a/src/qemu/qemu_process.c b/src/qemu/qemu_process.c
index 76ccead..209c8cf 100644
--- a/src/qemu/qemu_process.c
+++ b/src/qemu/qemu_process.c
@@ -1928,7 +1928,7 @@ int qemuProcessStart(virConnectPtr conn,

     vm->def->id = driver->nextvmid++;

-    /* Run a early hook to set-up missing devices */
+    /* Run an early hook to set-up missing devices */
     if (virHookPresent(VIR_HOOK_DRIVER_QEMU)) {
         char *xml = virDomainDefFormat(vm->def, 0);
         int hookret;
@@ -2436,7 +2436,7 @@ retry:
     VIR_FREE(priv->vcpupids);
     priv->nvcpupids = 0;

-    /* The "release" hook cleans up additional ressources */
+    /* The "release" hook cleans up additional resources */
     if (virHookPresent(VIR_HOOK_DRIVER_QEMU)) {
         char *xml = virDomainDefFormat(vm->def, 0);

-- 
1.7.4