Add retry host cost weight function to sched docs

fixes bug 1025068

As in the bug report,
2) New filter scheduler cost function:
nova.scheduler.least_cost.retry_host_cost_fn -

Adds additional cost for retrying scheduling at a host that was
already used for a previous scheduling attempt.

retry_host_cost_fn_weight is the associated FLAG to configure
weight.

this patch just adds that in.

Change-Id: I2db67144f857c3efb883b9cac45e0d5a24ae4ca9

doc/src/docbkx/openstack-compute-admin/computescheduler.xml

@@ -467,7 +467,7 @@ noop_cost_fn_weight=1.0
             are added together. The scheduler selects the host that has the
             minimum weighted cost.
 
-        The Compute service comes with two cost functions:
+        The Compute service comes with three cost functions:
     </para>
         <section xml:id="compute_fill_first_cost_fn">
             <title>nova.scheduler.least_cost.compute_fill_first_cost_fn</title>
@@ -488,6 +488,16 @@ compute_fill_first_cost_fn_weight=-1.0
                 then the scheduler will favor hosts that have the most amount
                 of available RAM, leading to a "spread-first" behavior.</para>
         </section>
+        <section xml:id="compute_retry_host_cost_fn">
+            <title>nova.scheduler.least_cost.retry_host_cost_fn</title>
+            <para>This cost function adds additional cost for retrying 
+		scheduling a host that was already used for a previous
+		scheduling attempt. </para>
+	   <para> The normal method of using this function is to set 
+		<literal>retry_host_cost_fn_weight</literal>
+		to a positive value, so that hosts which consistently
+		encounter build failures will be used less often.</para>
+        </section>
         <section xml:id="noop_cost_fn">
             <title>nova.scheduler.least_cost.noop_cost_fn</title>
             <para>This cost function returns 1 for all hosts. It is a "no-op"

doc/src/docbkx/openstack-compute-admin/tables/scheduler-nova-conf.xml

@@ -68,6 +68,12 @@
                 cost function. A negative value will reverse
                 behavior: e.g. spread-first </para></td>
         </tr>
+        <tr>
+            <td><para> retry_host_cost_fn_weight=1.0 </para></td>
+            <td><para> (FloatOpt) How much weight to give the retry host
+                cost function. A negative value will reverse
+                behavior: e.g. use multiple-times-retried hosts first </para></td>
+        </tr>
         <tr>
             <td><para>
                 least_cost_functions=nova.scheduler.least_cost.compute_fill_first_cost_fn </para></td>