diff --git a/poky/documentation/ref-manual/ref-features.xml b/poky/documentation/ref-manual/ref-features.xml
new file mode 100644
index 0000000..8cab5ec
--- /dev/null
+++ b/poky/documentation/ref-manual/ref-features.xml
@@ -0,0 +1,461 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+<!--SPDX-License-Identifier: CC-BY-2.0-UK-->
+
+<chapter id='ref-features'>
+    <title>Features</title>
+
+    <para>
+        This chapter provides a reference of shipped machine and distro features
+        you can include as part of your image, a reference on image features you can
+        select, and a reference on feature backfilling.
+    </para>
+
+    <para>
+        Features provide a mechanism for working out which packages
+        should be included in the generated images.
+        Distributions can select which features they want to support through the
+        <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>
+        variable, which is set or appended to in a distribution's configuration file such as
+        <filename>poky.conf</filename>,
+        <filename>poky-tiny.conf</filename>,
+        <filename>poky-lsb.conf</filename> and so forth.
+        Machine features are set in the
+        <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>
+        variable, which is set in the machine configuration file and
+        specifies the hardware features for a given machine.
+    </para>
+
+    <para>
+        These two variables combine to work out which kernel modules,
+        utilities, and other packages to include.
+        A given distribution can support a selected subset of features so some machine features might not
+        be included if the distribution itself does not support them.
+    </para>
+
+    <para>
+        One method you can use to determine which recipes are checking to see if a
+        particular feature is contained or not is to <filename>grep</filename> through
+        the <link linkend='metadata'>Metadata</link>
+        for the feature.
+        Here is an example that discovers the recipes whose build is potentially
+        changed based on a given feature:
+        <literallayout class='monospaced'>
+     $ cd poky
+     $ git grep 'contains.*MACHINE_FEATURES.*<replaceable>feature</replaceable>'
+        </literallayout>
+    </para>
+
+    <section id='ref-features-machine'>
+        <title>Machine Features</title>
+
+        <para>
+            The items below are features you can use with
+            <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>.
+            Features do not have a one-to-one correspondence to packages, and they can
+            go beyond simply controlling the installation of a package or packages.
+            Sometimes a feature can influence how certain recipes are built.
+            For example, a feature might determine whether a particular configure option
+            is specified within the
+            <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
+            task for a particular recipe.
+        </para>
+
+        <para>
+            This feature list only represents features as shipped with the Yocto Project metadata:
+            <itemizedlist>
+                <listitem><para><emphasis>acpi:</emphasis> Hardware has ACPI (x86/x86_64 only)
+                    </para></listitem>
+                <listitem><para><emphasis>alsa:</emphasis> Hardware has ALSA audio drivers
+                    </para></listitem>
+                <listitem><para><emphasis>apm:</emphasis> Hardware uses APM (or APM emulation)
+                    </para></listitem>
+                <listitem><para><emphasis>bluetooth:</emphasis> Hardware has integrated BT
+                    </para></listitem>
+                <listitem><para><emphasis>efi:</emphasis> Support for booting through EFI
+                    </para></listitem>
+                <listitem><para><emphasis>ext2:</emphasis> Hardware HDD or Microdrive
+                    </para></listitem>
+                <listitem><para><emphasis>keyboard:</emphasis> Hardware has a keyboard
+                    </para></listitem>
+                <listitem><para><emphasis>pcbios:</emphasis> Support for booting through BIOS
+                    </para></listitem>
+                <listitem><para><emphasis>pci:</emphasis> Hardware has a PCI bus
+                    </para></listitem>
+                <listitem><para><emphasis>pcmcia:</emphasis> Hardware has PCMCIA or CompactFlash sockets
+                    </para></listitem>
+                <listitem><para><emphasis>phone:</emphasis> Mobile phone (voice) support
+                    </para></listitem>
+                <listitem><para><emphasis>qvga:</emphasis> Machine has a QVGA (320x240) display
+                    </para></listitem>
+                <listitem><para><emphasis>rtc:</emphasis> Machine has a Real-Time Clock
+                    </para></listitem>
+                <listitem><para><emphasis>screen:</emphasis> Hardware has a screen
+                    </para></listitem>
+                <listitem><para><emphasis>serial:</emphasis> Hardware has serial support (usually RS232)
+                    </para></listitem>
+                <listitem><para><emphasis>touchscreen:</emphasis> Hardware has a touchscreen
+                    </para></listitem>
+                <listitem><para><emphasis>usbgadget:</emphasis> Hardware is USB gadget device capable
+                    </para></listitem>
+                <listitem><para><emphasis>usbhost:</emphasis> Hardware is USB Host capable
+                    </para></listitem>
+                <listitem><para><emphasis>vfat:</emphasis> FAT file system support
+                    </para></listitem>
+                <listitem><para><emphasis>wifi:</emphasis> Hardware has integrated WiFi
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
+
+    <section id='ref-features-distro'>
+        <title>Distro Features</title>
+
+        <para>
+            The items below are features you can use with
+            <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
+            to enable features across your distribution.
+            Features do not have a one-to-one correspondence to packages,
+            and they can go beyond simply controlling the installation of a
+            package or packages.
+            In most cases, the presence or absence of a feature translates to
+            the appropriate option supplied to the configure script during the
+            <link linkend='ref-tasks-configure'><filename>do_configure</filename></link>
+            task for the recipes that optionally
+            support the feature.
+        </para>
+
+        <para>
+            Some distro features are also machine features.
+            These select features make sense to be controlled both at
+            the machine and distribution configuration level.
+            See the
+            <link linkend='var-COMBINED_FEATURES'><filename>COMBINED_FEATURES</filename></link>
+            variable for more information.
+        </para>
+
+        <para>
+            This list only represents features as shipped with the Yocto Project metadata:
+            <itemizedlist>
+                <listitem><para><emphasis>alsa:</emphasis> Include ALSA support
+                    (OSS compatibility kernel modules installed if available).
+                    </para></listitem>
+                <listitem><para><emphasis>api-documentation:</emphasis>
+                    Enables generation of API documentation during recipe
+                    builds.
+                    The resulting documentation is added to SDK tarballs
+                    when the
+                    <filename>bitbake -c populate_sdk</filename> command
+                    is used.
+                    See the
+                    "<ulink url='&YOCTO_DOCS_SDK_URL;#adding-api-documentation-to-the-standard-sdk'>Adding API Documentation to the Standard SDK</ulink>"
+                    section in the Yocto Project Application Development and
+                    the Extensible Software Development Kit (eSDK) manual.
+                    </para></listitem>
+                <listitem><para><emphasis>bluetooth:</emphasis> Include
+                    bluetooth support (integrated BT only).</para></listitem>
+                <listitem><para><emphasis>cramfs:</emphasis> Include CramFS
+                    support.</para></listitem>
+                <listitem><para><emphasis>directfb:</emphasis>
+                    Include DirectFB support.
+                    </para></listitem>
+                <listitem><para><emphasis>ext2:</emphasis> Include tools for
+                    supporting for devices with internal HDD/Microdrive for
+                    storing files (instead of Flash only devices).
+                    </para></listitem>
+                <listitem><para><emphasis>ipsec:</emphasis> Include IPSec
+                    support.</para></listitem>
+                <listitem><para><emphasis>ipv6:</emphasis> Include IPv6 support.
+                    </para></listitem>
+                <listitem><para><emphasis>keyboard:</emphasis> Include keyboard
+                    support (e.g. keymaps will be loaded during boot).
+                    </para></listitem>
+                <listitem><para><emphasis>ldconfig:</emphasis>
+                    Include support for ldconfig and
+                    <filename>ld.so.conf</filename> on the target.
+                    </para></listitem>
+                <listitem><para><emphasis>nfs:</emphasis> Include NFS client
+                    support (for mounting NFS exports on device).
+                    </para></listitem>
+                <listitem><para><emphasis>opengl:</emphasis>
+                    Include the Open Graphics Library, which is a
+                    cross-language, multi-platform application programming
+                    interface used for rendering two and three-dimensional
+                    graphics.</para></listitem>
+                <listitem><para><emphasis>pci:</emphasis> Include PCI bus
+                    support.</para></listitem>
+                <listitem><para><emphasis>pcmcia:</emphasis> Include
+                    PCMCIA/CompactFlash support.</para></listitem>
+                <listitem><para><emphasis>ppp:</emphasis> Include PPP dialup
+                    support.</para></listitem>
+                <listitem><para><emphasis>ptest:</emphasis> Enables building
+                    the package tests where supported by individual recipes.
+                    For more information on package tests, see the
+                    "<ulink url='&YOCTO_DOCS_DEV_URL;#testing-packages-with-ptest'>Testing Packages With ptest</ulink>"
+                    section in the Yocto Project Development Tasks Manual.
+                    </para></listitem>
+                <listitem><para><emphasis>smbfs:</emphasis> Include SMB networks
+                    client support (for mounting Samba/Microsoft Windows shares
+                    on device).</para></listitem>
+                <listitem><para><emphasis>systemd:</emphasis> Include support
+                    for this <filename>init</filename> manager, which is a full
+                    replacement of for <filename>init</filename> with parallel
+                    starting of services, reduced shell overhead, and other
+                    features.
+                    This <filename>init</filename> manager is used by many
+                    distributions.</para></listitem>
+                <listitem><para><emphasis>usbgadget:</emphasis> Include USB
+                    Gadget Device support (for USB networking/serial/storage).
+                    </para></listitem>
+                <listitem><para><emphasis>usbhost:</emphasis> Include USB Host
+                    support (allows to connect external keyboard, mouse,
+                    storage, network etc).</para></listitem>
+                <listitem><para><emphasis>usrmerge:</emphasis> Merges the 
+                    <filename>/bin</filename>, <filename>/sbin</filename>, 
+                    <filename>/lib</filename>, and <filename>/lib64</filename>       
+                    directories into their respective counterparts in the 
+                    <filename>/usr</filename> directory to provide better package 
+                   and application compatibility.</para></listitem>
+                <listitem><para><emphasis>wayland:</emphasis> Include the
+                    Wayland display server protocol and the library that
+                    supports it.</para></listitem>
+                <listitem><para><emphasis>wifi:</emphasis> Include WiFi support
+                    (integrated only).</para></listitem>
+                <listitem><para><emphasis>x11:</emphasis> Include the X server
+                    and libraries.</para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
+
+    <section id='ref-features-image'>
+        <title>Image Features</title>
+
+        <para>
+            The contents of images generated by the OpenEmbedded build system
+            can be controlled by the
+            <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
+            and
+            <link linkend='var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></link>
+            variables that you typically configure in your image recipes.
+            Through these variables, you can add several different
+            predefined packages such as development utilities or packages with
+            debug information needed to investigate application problems or
+            profile applications.
+        </para>
+
+        <para>
+            The following image features are available for all images:
+            <itemizedlist>
+                <listitem><para><emphasis>allow-empty-password:</emphasis>
+                    Allows Dropbear and OpenSSH to accept root logins
+                    and logins from accounts having an empty password string.
+                    </para></listitem>
+                <listitem><para><emphasis>dbg-pkgs:</emphasis>
+                    Installs debug symbol packages for all packages installed
+                    in a given image.
+                    </para></listitem>
+                <listitem><para><emphasis>debug-tweaks:</emphasis>
+                    Makes an image suitable for development (e.g.
+                    allows root logins without passwords and enables
+                    post-installation logging).
+                    See the 'allow-empty-password', 'empty-root-password',
+                    and 'post-install-logging' features in this list for
+                    additional information.
+                    </para></listitem>
+                <listitem><para><emphasis>dev-pkgs:</emphasis>
+                    Installs development packages (headers and extra library
+                    links) for all packages installed in a given image.
+                    </para></listitem>
+                <listitem><para><emphasis>doc-pkgs:</emphasis> Installs
+                    documentation packages for all packages installed in a
+                    given image.
+                    </para></listitem>
+                <listitem><para><emphasis>empty-root-password:</emphasis>
+                    Sets the root password to an empty string, which allows
+                    logins with a blank password.
+                    </para></listitem>
+                <listitem><para><emphasis>package-management:</emphasis>
+                    Installs package management tools and preserves the package
+                    manager database.
+                    </para></listitem>
+                <listitem><para><emphasis>post-install-logging:</emphasis>
+                    Enables logging postinstall script runs to
+                    the <filename>/var/log/postinstall.log</filename> file
+                    on first boot of the image on the target system.
+                    <note>
+                        To make the <filename>/var/log</filename> directory
+                        on the target persistent, use the
+                        <link linkend='var-VOLATILE_LOG_DIR'><filename>VOLATILE_LOG_DIR</filename></link>
+                        variable by setting it to "no".
+                    </note>
+                    </para></listitem>
+                <listitem><para><emphasis>ptest-pkgs:</emphasis>
+                    Installs ptest packages for all ptest-enabled recipes.
+                    </para></listitem>
+                <listitem><para><emphasis>read-only-rootfs:</emphasis>
+                    Creates an image whose root filesystem is read-only.
+                    See the
+                    "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem'>Creating a Read-Only Root Filesystem</ulink>"
+                    section in the Yocto Project Development Tasks Manual for
+                    more information.
+                    </para></listitem>
+                <listitem><para><emphasis>splash:</emphasis>
+                    Enables showing a splash screen during boot.
+                    By default, this screen is provided by
+                    <filename>psplash</filename>, which does allow
+                    customization.
+                    If you prefer to use an alternative splash screen package,
+                    you can do so by setting the <filename>SPLASH</filename>
+                    variable to a different package name (or names) within the
+                    image recipe or at the distro configuration level.
+                    </para></listitem>
+                <listitem><para><emphasis>staticdev-pkgs:</emphasis>
+                    Installs static development packages, which are
+                    static libraries (i.e. <filename>*.a</filename> files), for
+                    all packages installed in a given image.
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+
+        <para>
+            Some image features are available only when you inherit the
+            <link linkend='ref-classes-core-image'><filename>core-image</filename></link>
+            class.
+            The current list of these valid features is as follows:
+            <itemizedlist>
+                <listitem><para><emphasis>hwcodecs:</emphasis> Installs
+                    hardware acceleration codecs.
+                    </para></listitem>
+                <listitem><para><emphasis>nfs-server:</emphasis>
+                    Installs an NFS server.
+                    </para></listitem>
+                <listitem><para><emphasis>perf:</emphasis>
+                    Installs profiling tools such as
+                    <filename>perf</filename>, <filename>systemtap</filename>,
+                    and <filename>LTTng</filename>.
+                    For general information on user-space tools, see the
+                    <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
+                    manual.
+                    </para></listitem>
+                <listitem><para><emphasis>ssh-server-dropbear:</emphasis>
+                    Installs the Dropbear minimal SSH server.
+                    </para></listitem>
+                <listitem><para><emphasis>ssh-server-openssh:</emphasis>
+                    Installs the OpenSSH SSH server, which is more
+                    full-featured than Dropbear.
+                    Note that if both the OpenSSH SSH server and the Dropbear
+                    minimal SSH server are present in
+                    <filename>IMAGE_FEATURES</filename>, then OpenSSH will take
+                    precedence and Dropbear will not be installed.
+                    </para></listitem>
+                <listitem><para><emphasis>tools-debug:</emphasis>
+                    Installs debugging tools such as
+                    <filename>strace</filename> and <filename>gdb</filename>.
+                    For information on GDB, see the
+                    "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-gdb-remotedebug'>Debugging With the GNU Project Debugger (GDB) Remotely</ulink>"
+                    section in the Yocto Project Development Tasks Manual.
+                    For information on tracing and profiling, see the
+                    <ulink url='&YOCTO_DOCS_PROF_URL;'>Yocto Project Profiling and Tracing Manual</ulink>.
+                    </para></listitem>
+                <listitem><para><emphasis>tools-sdk:</emphasis>
+                    Installs a full SDK that runs on the device.
+                    </para></listitem>
+                <listitem><para><emphasis>tools-testapps:</emphasis>
+                    Installs device testing tools (e.g. touchscreen debugging).
+                    </para></listitem>
+                <listitem><para><emphasis>x11:</emphasis>
+                    Installs the X server.
+                    </para></listitem>
+                <listitem><para><emphasis>x11-base:</emphasis>
+                    Installs the X server with a minimal environment.
+                    </para></listitem>
+                <listitem><para><emphasis>x11-sato:</emphasis>
+                    Installs the OpenedHand Sato environment.
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+
+    </section>
+
+    <section id='ref-features-backfill'>
+        <title>Feature Backfilling</title>
+
+        <para>
+            Sometimes it is necessary in the OpenEmbedded build system to extend
+            <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>
+            or <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
+            to control functionality that was previously enabled and not able
+            to be disabled.
+            For these cases, we need to add an
+            additional feature item to appear in one of these variables,
+            but we do not want to force developers who have existing values
+            of the variables in their configuration to add the new feature
+            in order to retain the same overall level of functionality.
+            Thus, the OpenEmbedded build system has a mechanism to
+            automatically "backfill" these added features into existing
+            distro or machine configurations.
+            You can see the list of features for which this is done by
+            finding the
+            <link linkend='var-DISTRO_FEATURES_BACKFILL'><filename>DISTRO_FEATURES_BACKFILL</filename></link>
+            and <link linkend='var-MACHINE_FEATURES_BACKFILL'><filename>MACHINE_FEATURES_BACKFILL</filename></link>
+            variables in the <filename>meta/conf/bitbake.conf</filename> file.
+        </para>
+
+        <para>
+            Because such features are backfilled by default into all
+            configurations as described in the previous paragraph, developers
+            who wish to disable the new features need to be able to selectively
+            prevent the backfilling from occurring.
+            They can do this by adding the undesired feature or features to the
+            <link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename></link>
+            or <link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename></link>
+            variables for distro features and machine features respectively.
+        </para>
+
+        <para>
+            Here are two examples to help illustrate feature backfilling:
+            <itemizedlist>
+                <listitem><para><emphasis>The "pulseaudio" distro feature option</emphasis>:
+                    Previously, PulseAudio support was enabled within the Qt and
+                    GStreamer frameworks.
+                    Because of this, the feature is backfilled and thus
+                    enabled for all distros through the
+                    <filename>DISTRO_FEATURES_BACKFILL</filename>
+                    variable in the <filename>meta/conf/bitbake.conf</filename> file.
+                    However, your distro needs to disable the feature.
+                    You can disable the feature without affecting
+                    other existing distro configurations that need PulseAudio support
+                    by adding "pulseaudio" to
+                    <filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename>
+                    in your distro's <filename>.conf</filename> file.
+                    Adding the feature to this variable when it also
+                    exists in the <filename>DISTRO_FEATURES_BACKFILL</filename>
+                    variable prevents the build system from adding the feature to
+                    your configuration's <filename>DISTRO_FEATURES</filename>, effectively disabling
+                    the feature for that particular distro.</para></listitem>
+                <listitem><para><emphasis>The "rtc" machine feature option</emphasis>:
+                    Previously, real time clock (RTC) support was enabled for all
+                    target devices.
+                    Because of this, the feature is backfilled and thus enabled
+                    for all machines through the <filename>MACHINE_FEATURES_BACKFILL</filename>
+                    variable in the <filename>meta/conf/bitbake.conf</filename> file.
+                    However, your target device does not have this capability.
+                    You can disable RTC support for your device without
+                    affecting other machines that need RTC support
+                    by adding the feature to your machine's
+                    <filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename>
+                    list in the machine's <filename>.conf</filename> file.
+                    Adding the feature to this variable when it also
+                    exists in the <filename>MACHINE_FEATURES_BACKFILL</filename>
+                    variable prevents the build system from adding the feature to
+                    your configuration's <filename>MACHINE_FEATURES</filename>, effectively
+                    disabling RTC support for that particular machine.</para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
+</chapter>
+
+<!--
+vim: expandtab tw=80 ts=4 spell spelllang=en_gb
+-->