documentation: poky-ref-manual - New backfill variables and section.

Document DISTRO_FEATURES_BACKFILL and MACHINE_FEATURES_BACKFILL. We may
wish to expand upon this in future, but at least this explains what
these variables are for and how to use them.

Also add a link from the DISTRO_FEATURES entry to the section that lists
valid DISTRO_FEATURES items.

(From yocto-docs rev: 018af5c28b44464ae66646780ade910bdcab2bef)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

2 files changed, 108 insertions, 1 deletions

diff --git a/documentation/poky-ref-manual/ref-features.xml b/documentation/poky-ref-manual/ref-features.xml
index 159d56dabc..c42a4fd807 100644
--- a/documentation/poky-ref-manual/ref-features.xml
+++ b/documentation/poky-ref-manual/ref-features.xml
@@ -171,6 +171,61 @@
             </itemizedlist>
         </para>
     </section>
+
+    <section id='ref-features-backfill'>
+        <title>Feature Backfilling</title>
+
+        <para>
+            Sometimes, it is necessary for a new feature to be added to control existing
+            functionality that was previously enabled by default and not able to be disabled.
+            In order to ensure that the feature remains enabled for users with existing
+            configurations that upgrade to a new version of the core metadata without that 
+            configuration having to be changed, while still allowing others who want to turn
+            the feature off to do so, the backfilling mechanism was introduced. 
+            This 
+            functionality is available for <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>
+            and <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>.
+        </para>
+
+        <para>
+            An example is the "pulseaudio" distro feature. 
+            Previously, PulseAudio support
+            was enabled within the Qt and GStreamer frameworks.
+            However some users desired
+            to be able to disable this. 
+            To allow this to be disabled without affecting 
+            existing configurations in which PulseAudio support should remain enabled,
+            "pulseaudio" was added to 
+            <filename><link linkend='var-DISTRO_FEATURES_BACKFILL'>DISTRO_FEATURES_BACKFILL</link></filename>
+            within <filename>meta/conf/bitbake.conf</filename>.
+            This means that "pulseaudio"
+            is automatically added to <filename>DISTRO_FEATURES</filename> without the distro
+            configuration needing to be updated to do so itself.
+            Those who do not want PulseAudio support can add "pulseaudio" to
+            <filename><link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'>DISTRO_FEATURES_BACKFILL_CONSIDERED</link></filename>
+            in their distro <filename>.conf</filename> file and this will disable adding "pulseaudio" to
+            <filename>DISTRO_FEATURES</filename>.
+        </para>
+
+        <para>
+            Another example is the "rtc" machine feature. 
+            Previously, real time clock (RTC)
+            support was enabled for all target devices.
+            However certain targets do not have
+            this capability. 
+            To allow this to be disabled by such machines without affecting
+            other machines in which RTC support should remain enabled, "rtc" was added to 
+            <filename><link linkend='var-MACHINE_FEATURES_BACKFILL'>MACHINE_FEATURES_BACKFILL</link></filename>
+            within <filename>meta/conf/bitbake.conf</filename>.
+            This means that "rtc"
+            is automatically added to <filename>MACHINE_FEATURES</filename> without the
+            machine configuration needing to be updated to do so itself.
+            For machines that not need RTC support can add "rtc" to
+            <filename><link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'>MACHINE_FEATURES_BACKFILL_CONSIDERED</link></filename>
+            in their machine <filename>.conf</filename> file and this will disable adding "rtc" to
+            <filename>MACHINE_FEATURES</filename>.
+        </para>
+    </section>
 </chapter>
 
 <!-- 
diff --git a/documentation/poky-ref-manual/ref-variables.xml b/documentation/poky-ref-manual/ref-variables.xml
index 2baed3788c..ca89a432fc 100644
--- a/documentation/poky-ref-manual/ref-variables.xml
+++ b/documentation/poky-ref-manual/ref-variables.xml
@@ -483,7 +483,35 @@
 
         <glossentry id='var-DISTRO_FEATURES'><glossterm>DISTRO_FEATURES</glossterm>
             <glossdef>
-                <para>The features of the distribution.</para>
+                <para>The features enabled for the distribution.
+                    For a list of valid features, see the
+                    "<link linkend='ref-features-distro'>Distro</link>"
+                    section.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-DISTRO_FEATURES_BACKFILL'><glossterm>DISTRO_FEATURES_BACKFILL</glossterm>
+            <glossdef>
+                <para>Features to be added to 
+                    <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>
+                    if not also present in 
+                    <filename><link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'>DISTRO_FEATURES_BACKFILL_CONSIDERED</link></filename>.
+                    See the "<link linkend='ref-features-backfill'>Feature Backfilling</link>" section for 
+                    more information.
+                    </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><glossterm>DISTRO_FEATURES_BACKFILL_CONSIDERED</glossterm>
+            <glossdef>
+                <para>Features from
+                    <filename><link linkend='var-DISTRO_FEATURES_BACKFILL'>DISTRO_FEATURES_BACKFILL</link></filename>
+                    that should not be added to
+                    <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>.
+                    See the "<link linkend='ref-features-backfill'>Feature Backfilling</link>" section for 
+                    more information.
+                    </para>
             </glossdef>
         </glossentry>
 
@@ -1536,6 +1564,30 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
             </glossdef>
          </glossentry>
 
+        <glossentry id='var-MACHINE_FEATURES_BACKFILL'><glossterm>MACHINE_FEATURES_BACKFILL</glossterm>
+            <glossdef>
+                <para>Features to be added to 
+                    <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>
+                    if not also present in 
+                    <filename><link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'>MACHINE_FEATURES_BACKFILL_CONSIDERED</link></filename>.
+                    See the <link linkend='ref-features-backfill'>Feature backfilling</link> section for 
+                    more information.
+                    </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><glossterm>MACHINE_FEATURES_BACKFILL_CONSIDERED</glossterm>
+            <glossdef>
+                <para>Features from
+                    <filename><link linkend='var-MACHINE_FEATURES_BACKFILL'>MACHINE_FEATURES_BACKFILL</link></filename>
+                    that should not be added to
+                    <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>.
+                    See the <link linkend='ref-features-backfill'>Feature backfilling</link> section for 
+                    more information.
+                    </para>
+            </glossdef>
+        </glossentry>
+
         <glossentry id='var-MAINTAINER'><glossterm>MAINTAINER</glossterm>
             <glossdef>
                 <para>The email address of the distribution maintainer.</para>