ref-manual: Updated the DISK_SIGNATURE description.

Fixes [YOCTO #6125]

Did some re-writing based on Jonathin Liu's feedback.

(From yocto-docs rev: bee4a584bcb1e70e9848324781c32d1d9e3d1fc2)

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

1 files changed, 27 insertions, 8 deletions

diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
index 7219fe6d2f..7a8ca3b94e 100644
--- a/documentation/ref-manual/ref-variables.xml
+++ b/documentation/ref-manual/ref-variables.xml
@@ -1620,26 +1620,45 @@
         <glossentry id='var-DISK_SIGNATURE'><glossterm>DISK_SIGNATURE</glossterm>
             <glossdef>
                 <para>
-                    Automatically generated random signature that allows the
-                    OpenEmbedded build system to create a boot
-                    loader configuration.
-                    <filename>DISK_SIGNATURE</filename> is different each time
-                    a <filename>directdisk</filename> image is built.
+                    A 32-bit MBR disk signature used by
+                    <filename>directdisk</filename> images.
                     <note>
                         The "live" option used with
                         <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
                         produces an image file that can be copied directly to
                         a CD or USB device and run as is.
                     </note>
-                    The auto-generated <filename>DISK_SIGNATURE</filename> sets
-                    <filename>SYSLINUX_ROOT</filename> as follows:
+                    By default, the signature is set to an automatically
+                    generated random value that allows the OpenEmbedded
+                    build system to create a boot loader.
+                    You can override the signature in the image recipe
+                    by setting <filename>DISK_SIGNATURE</filename> to an
+                    8-digit hex string.
+                    You might want to override
+                    <filename>DISK_SIGNATURE</filename> if you want the disk
+                    signature to remain constant between image builds.
+                </para>
+
+                <para>
+                    When using Linux 3.8 or later, you can use
+                    <filename>DISK_SIGNATURE</filename> to specify the root
+                    by UUID to allow the kernel to locate the root device
+                    even if the device name changes due to differences in
+                    hardware configuration.
+                    By default, <filename>SYSLINUX_ROOT</filename> is set
+                    as follows:
+                    <literallayout class='monospaced'>
+     SYSLINUX_ROOT = "root=/dev/sda2"
+                    </literallayout>
+                    However, you can change this to locate the root device
+                    using the disk signature instead:
                     <literallayout class='monospaced'>
      SYSLINUX_ROOT = "root=PARTUUID=${DISK_SIGNATURE}-02"
                     </literallayout>
                 </para>
 
                 <para>
-                    It is possible to set the
+                    As previously mentioned, it is possible to set the
                     <filename>DISK_SIGNATURE</filename> variable in your
                     <filename>local.conf</filename> file to a fixed
                     value if you do not want <filename>syslinux.cfg</filename>