docs: hvsupport: Add support for deprecating hypervisor implementations

Allow expressing that a hypervisor implementation was deleted by adding
a end-version when the implementation was removed to our hypervisor
support matrix.

This patch hacks the perl script that generates the support matrix to
support comments like:

.domainQemuAttach = qemuDomainQemuAttach, /* 0.8.3 (deprecated: 5.5.0) */

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
Reviewed-by: Ján Tomko <jtomko@redhat.com>
Reviewed-by: Andrea Bolognani <abologna@redhat.com>

diff --git a/docs/hvsupport.pl b/docs/hvsupport.pl
index a2b980c502a31c5fc9cd7cef21a30518732833f0..2ea245e83ad99ad5d2a4de8c951c62d29d979bb6 100755 (executable)
--- a/docs/hvsupport.pl
+++ b/docs/hvsupport.pl
@@ -234,10 +234,11 @@ foreach my $src (@srcs) {
             }
 
         } else {
-            if ($line =~ m!\s*\.(\w+)\s*=\s*(\w+)\s*,?\s*(?:/\*\s*(\d+\.\d+\.\d+)\s*\*/\s*)?$!) {
+            if ($line =~ m!\s*\.(\w+)\s*=\s*(\w+)\s*,?\s*(?:/\*\s*(\d+\.\d+\.\d+)\s*(?:\(deprecated:\s*(\d+\.\d+\.\d+)\))?\s*\*/\s*)?$!) {
                 my $api = $1;
                 my $meth = $2;
                 my $vers = $3;
+                my $depre = $4;
 
                 next if $api eq "no" || $api eq "name";
 
@@ -251,12 +252,16 @@ foreach my $src (@srcs) {
                     die "Found unexpected method $api in $ingrp\n";
                 }
 
-                $groups{$ingrp}->{drivers}->{$impl}->{$api} = $vers;
+                $groups{$ingrp}->{drivers}->{$impl}->{$api} = {};
+                $groups{$ingrp}->{drivers}->{$impl}->{$api}->{vers} = $vers;
+                $groups{$ingrp}->{drivers}->{$impl}->{$api}->{depre}  = $depre;
                 if ($api eq "domainMigratePrepare" ||
                     $api eq "domainMigratePrepare2" ||
                     $api eq "domainMigratePrepare3") {
-                    $groups{$ingrp}->{drivers}->{$impl}->{"domainMigrate"} = $vers
-                        unless $groups{$ingrp}->{drivers}->{$impl}->{"domainMigrate"};
+                    if (!$groups{$ingrp}->{drivers}->{$impl}->{"domainMigrate"}) {
+                        $groups{$ingrp}->{drivers}->{$impl}->{"domainMigrate"} = {};
+                        $groups{$ingrp}->{drivers}->{$impl}->{"domainMigrate"}->{vers} = $vers;
+                    }
                 }
 
             } elsif ($line =~ /}/) {
@@ -280,7 +285,7 @@ $groups{virHypervisorDriver}->{apis}->{"domainMigrate"} = "virDomainMigrate";
 my $openAuthVers = (0 * 1000 * 1000) + (4 * 1000) + 0;
 
 foreach my $drv (keys %{$groups{"virHypervisorDriver"}->{drivers}}) {
-    my $openVersStr = $groups{"virHypervisorDriver"}->{drivers}->{$drv}->{"connectOpen"};
+    my $openVersStr = $groups{"virHypervisorDriver"}->{drivers}->{$drv}->{"connectOpen"}->{vers};
     my $openVers;
     if ($openVersStr =~ /(\d+)\.(\d+)\.(\d+)/) {
         $openVers = ($1 * 1000 * 1000) + ($2 * 1000) + $3;
@@ -290,14 +295,16 @@ foreach my $drv (keys %{$groups{"virHypervisorDriver"}->{drivers}}) {
     $groups{"virHypervisorDriver"}->{drivers}->{$drv}->{"connectOpenReadOnly"} =
         $groups{"virHypervisorDriver"}->{drivers}->{$drv}->{"connectOpen"};
 
+    $groups{"virHypervisorDriver"}->{drivers}->{$drv}->{"connectOpenAuth"} = {};
+
     # virConnectOpenAuth is always 0.4.0 if the driver existed
     # before this time, otherwise it matches the version of
     # the driver's virConnectOpen entry
     if ($openVersStr eq "Y" ||
         $openVers >= $openAuthVers) {
-        $groups{"virHypervisorDriver"}->{drivers}->{$drv}->{"connectOpenAuth"} = $openVersStr;
+        $groups{"virHypervisorDriver"}->{drivers}->{$drv}->{"connectOpenAuth"}->{vers} = $openVersStr;
     } else {
-        $groups{"virHypervisorDriver"}->{drivers}->{$drv}->{"connectOpenAuth"} = "0.4.0";
+        $groups{"virHypervisorDriver"}->{drivers}->{$drv}->{"connectOpenAuth"}->{vers} = "0.4.0";
     }
 }
 
@@ -309,21 +316,23 @@ $groups{virHypervisorDriver}->{apis}->{"domainCreateLinux"} = "virDomainCreateLi
 my $createAPIVers = (0 * 1000 * 1000) + (0 * 1000) + 3;
 
 foreach my $drv (keys %{$groups{"virHypervisorDriver"}->{drivers}}) {
-    my $createVersStr = $groups{"virHypervisorDriver"}->{drivers}->{$drv}->{"domainCreateXML"};
+    my $createVersStr = $groups{"virHypervisorDriver"}->{drivers}->{$drv}->{"domainCreateXML"}->{vers};
     next unless defined $createVersStr;
     my $createVers;
     if ($createVersStr =~ /(\d+)\.(\d+)\.(\d+)/) {
         $createVers = ($1 * 1000 * 1000) + ($2 * 1000) + $3;
     }
 
+    $groups{"virHypervisorDriver"}->{drivers}->{$drv}->{"domainCreateLinux"} = {};
+
     # virCreateLinux is always 0.0.3 if the driver existed
     # before this time, otherwise it matches the version of
     # the driver's virCreateXML entry
     if ($createVersStr eq "Y" ||
         $createVers >= $createAPIVers) {
-        $groups{"virHypervisorDriver"}->{drivers}->{$drv}->{"domainCreateLinux"} = $createVersStr;
+        $groups{"virHypervisorDriver"}->{drivers}->{$drv}->{"domainCreateLinux"}->{vers} = $createVersStr;
     } else {
-        $groups{"virHypervisorDriver"}->{drivers}->{$drv}->{"domainCreateLinux"} = "0.0.3";
+        $groups{"virHypervisorDriver"}->{drivers}->{$drv}->{"domainCreateLinux"}->{vers} = "0.0.3";
     }
 }
 
@@ -342,7 +351,9 @@ print <<EOF;
 <p>
 This page documents which <a href="html/">libvirt calls</a> work on
 which libvirt drivers / hypervisors, and which version the API appeared
-in.
+in. If a hypervisor driver deprecated the API, the version when it
+was removed is also mentioned (highlighted in
+<span class="deprecatedhv">dark red</span>).
 </p>
 
 EOF
@@ -395,11 +406,16 @@ EOF
 EOF
 
         foreach my $drv (sort {$a cmp $b } keys %{$groups{$grp}->{drivers}}) {
+            print "<td>";
             if (exists $groups{$grp}->{drivers}->{$drv}->{$field}) {
-                print "<td>", $groups{$grp}->{drivers}->{$drv}->{$field}, "</td>\n";
-            } else {
-                print "<td></td>\n";
+                if ($groups{$grp}->{drivers}->{$drv}->{$field}->{vers}) {
+                    print $groups{$grp}->{drivers}->{$drv}->{$field}->{vers};
+                }
+                if ($groups{$grp}->{drivers}->{$drv}->{$field}->{depre}) {
+                    print " - <span class=\"deprecatedhv\">", $groups{$grp}->{drivers}->{$drv}->{$field}->{depre}, "</span>";
+                }
             }
+            print "</td>\n";
         }
 
         print <<EOF;

diff --git a/docs/libvirt.css b/docs/libvirt.css
index 0d2d5f8ace25f51edd8f2b7ca6aeef8367d533be..8238f0275c80081d2019b4cf94b8b1f4248f4248 100644 (file)
--- a/docs/libvirt.css
+++ b/docs/libvirt.css
@@ -581,3 +581,7 @@ td.enumvalue {
 #advancedsearch label {
     display: inline;
 }
+
+.deprecatedhv {
+    color: darkred;
+}