yocto-docs updates

index 19ce9ab..a1669f1 100644
@@ -685,44 +685,165 @@
         <title>Enabling Commercially Licensed Recipes</title>
 
         <para>
-            By default, the Yocto Project build system disables components that 
-            have commercial licensing requirements.
-            The following four statements in the
-            <filename>$HOME/poky/meta/conf/distro/poky.conf</filename> file
-            disable components:
+            By default, the Yocto Project build system disables
+            components that have commercial or other special licensing
+            requirements.  Such requirements are defined on a
+            recipe-by-recipe basis via a LICENSE_FLAGS variable
+            definition in the affected recipe.  For instance, the
+            <filename>$HOME/poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename>
+            recipe contains the statement:
             <literallayout class='monospaced'>
-     COMMERCIAL_LICENSE ?= "lame gst-fluendo-mp3 libmad mpeg2dec ffmpeg qmmp"
-     COMMERCIAL_AUDIO_PLUGINS ?= ""
-     COMMERCIAL_VIDEO_PLUGINS ?= ""
-     COMMERCIAL_QT ?= "qmmp"
+     LICENSE_FLAGS = "commercial"
             </literallayout>
-        </para> 
-
-        <para>
-            If you want to enable these components, you can do so by making sure you have
-            the following statements in the configuration file:
+            Another example would be the following from a recipe in another layer:
             <literallayout class='monospaced'>
-     COMMERCIAL_AUDIO_PLUGINS = "gst-plugins-ugly-mad \
-        gst-plugins-ugly-mpegaudioparse"
-     COMMERCIAL_VIDEO_PLUGINS = "gst-plugins-ugly-mpeg2dec \
-        gst-plugins-ugly-mpegstream gst-plugins-bad-mpegvideoparse"
-     COMMERCIAL_LICENSE = ""
-     COMMERCIAL_QT = ""
+     LICENSE_FLAGS = "license_${PN}_${PV}"
             </literallayout>
-        </para>
-
-        <para>
-            Excluding a package name from the 
-            <filename>COMMERCIAL_LICENSE</filename> or 
-            <filename>COMMERCIAL_QT</filename> statement enables that package.  
-        </para>
-
-        <para>
-            Specifying audio and video plug-ins as part of the 
-            <filename>COMMERCIAL_AUDIO_PLUGINS</filename> and 
-            <filename>COMMERCIAL_VIDEO_PLUGINS</filename> statements includes 
-            the plug-ins into built images - thus adding support for media formats.
-        </para>
+	    In order for a component restricted by a LICENSE_FLAGS
+	    definition to be enabled and included in an image, it
+	    needs to have a matching entry in the global
+	    LICENSE_FLAGS_WHITELIST variable, which is a variable
+	    typically defined in your local.conf file.  For instance,
+	    to enable
+	    the <filename>$HOME/poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename>
+	    package, you could add either the string
+	    "commercial_gst-plugins-ugly" or the more general
+	    "commercial" to LICENSE_FLAGS_WHITELIST (see section
+	    3.3.2.1 for a full explanation of LICENSE_FLAGS matching):
+            <literallayout class='monospaced'>
+     LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly"
+            </literallayout>
+	    Likewise, to additionally enable the package containing
+	    LICENSE_FLAGS = "license_${PN}_${PV}", and assuming for
+	    example that the actual recipe name was 'emgd_1.10.bb',
+	    the following string would enable that package as well as
+	    the original gst-plugins-ugly package:
+            <literallayout class='monospaced'>
+     LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly license_emgd_1.10"
+            </literallayout>
+	    As a convenience to the user, the complete license string
+	    doesn't need to be specified in the whitelist for every
+	    package - an abbreviated form can be used, which consists
+	    of just the first portion(s) of the license string before
+	    the initial underscore(s).  A partial string will match
+	    any license that contains the given string as the first
+	    portion of its license.  For example, the following
+	    whitelist string will also match both of the packages
+	    mentioned above (as well as any other packages that have
+	    licenses starting with "commercial" or "license").
+            <literallayout class='monospaced'>
+     LICENSE_FLAGS_WHITELIST = "commercial license"
+            </literallayout>
+            <section id="enabling-commercially-licensed-recipes-matching">
+              <title>Explanation of how LICENSE_FLAGS matching works</title>
+              <para>
+		The definition of 'matching' in reference to a
+		recipe's LICENSE_FLAGS setting is simple, but there
+		are a couple things users need to know in order to
+		correctly and effectively use it.  Before a flag
+		defined by a particular recipe is tested against the
+		contents of the LICENSE_FLAGS_WHITELIST variable, the
+		string '_${PN}' (with PN expanded of course) is
+		appended to the flag, thus automatically making each
+		LICENSE_FLAGS value recipe-specific.  That string is
+		then matched against the whitelist.  So if the user
+		specifies LICENSE_FLAGS = 'commercial' in recipe
+		'foo', the string 'commercial_foo' would normally be
+		what is specified in the whitelist in order for it to
+		match.
+              </para>
+              <para>
+		However, the user can also broaden the match by
+		putting any '_'-separated beginning subset of a
+		LICENSE_FLAGS flag in the whitelist, which will also
+		match.  For example, simply specifying 'commercial' in
+		the whitelist would match any expanded LICENSE_FLAGS
+		definition starting with 'commercial' such as
+		'commercial_foo' and 'commercial_bar', which are the
+		strings that would be automatically generated for
+		hypothetical 'foo' and 'bar' recipes assuming those
+		recipes had simply specified LICENSE_FLAGS =
+		'commercial'.
+              </para>
+              <para>
+		This allows for a range of specificity for the items
+		in the whitelist, from more general to perfectly
+		specific.  So users have the choice of exhaustively
+		enumerating each license flag in the whitelist to
+		allow only those specific recipes into the image, or
+		of using a more general string to pick up anything
+		matching just the first component(s) of the specified
+		string.
+              </para>
+              <para>
+		Note that this scheme works even if the flag already
+		has '_${PN}' appended - the extra '_${PN}' is
+		redundant, but doesn't affect the outcome.  For
+		example, a license flag of 'commercial_1.2_foo' would
+		turn into 'commercial_1.2_foo_foo' and would match
+		both the general 'commercial' and the specific
+		'commercial_1.2_foo', as expected (it would also match
+		commercial_1.2_foo_foo' and 'commercial_1.2', which
+		don't make much sense as far as something a user would
+		think of specifying in the whitelist).  For a
+		versioned string, the user could instead specify
+		'commercial_foo_1.2', which would turn into
+		'commercial_foo_1.2_foo', but which would as expected
+		allow the user to pick up this package along with
+		anything else 'commercial' by specifying 'commercial'
+		in the whitelist, or anything with a 'commercial_foo'
+		license regardless of version by using
+		'commercial_foo' in the whitelist, or
+		'commercial_foo_1.1' to be completely specific about
+		package and version.
+              </para>
+            </section>
+        </para>
+        <para>
+          <section id="enabling-commercially-licensed-recipes-helpers">
+            <title>Other Variables Related to Commercial Licenses</title>
+            <para>
+	      There are a few other variables related to commercial
+	      license handling defined in the
+              <filename>$HOME/poky/meta/conf/distro/include/default-distrovars.inc</filename> file:
+              <literallayout class='monospaced'>
+		COMMERCIAL_AUDIO_PLUGINS ?= ""
+		COMMERCIAL_VIDEO_PLUGINS ?= ""
+		COMMERCIAL_QT = ""
+              </literallayout>
+            </para> 
+            <para>
+              If you want to enable these components, you can do so by making sure you have
+              the following statements in your local.conf configuration file:
+              <literallayout class='monospaced'>
+		COMMERCIAL_AUDIO_PLUGINS = "gst-plugins-ugly-mad \
+		gst-plugins-ugly-mpegaudioparse"
+		COMMERCIAL_VIDEO_PLUGINS = "gst-plugins-ugly-mpeg2dec \
+		gst-plugins-ugly-mpegstream gst-plugins-bad-mpegvideoparse"
+		COMMERCIAL_QT ?= "qmmp"
+		LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly commercial_gst-plugins-bad commercial_qmmp"
+              </literallayout>
+	      Of course, you could also create a matching whitelist
+	      for those components using the more general "commercial"
+	      in the whitelist, but that would also enable all the
+	      other packages with LICENSE_FLAGS containing
+	      "commercial", which you may or may not want:
+              <literallayout class='monospaced'>
+		LICENSE_FLAGS_WHITELIST = "commercial"
+              </literallayout>
+            </para>
+            <para>
+              Specifying audio and video plug-ins as part of the 
+              <filename>COMMERCIAL_AUDIO_PLUGINS</filename> and 
+              <filename>COMMERCIAL_VIDEO_PLUGINS</filename> statements
+              or commercial qt components as part of
+              the <filename>COMMERCIAL_QT</filename> statement (along
+              with the enabling LICENSE_FLAGS_WHITELIST) includes the
+              plug-ins or components into built images, thus adding
+              support for media formats or components.
+            </para>
+	  </section>
+	</para>
     </section>
 </section>
 </chapter>

index a8d571c..40d994a 100644
@@ -656,135 +656,125 @@
             </section>
         </section>
 
-        <section id='bsp-click-through-licensing'>
-            <title>BSP 'Click-Through' Licensing Procedure</title>
-
-            <note> This section describes how
-		click-through licensing is expected to work.
-                Currently, this functionality is not yet implemented.
-            </note>
-
+        <section id='bsp-licensing'>
+            <title>BSP Licensing Considerations</title>
             <para>
 	      In some cases, a BSP contains separately licensed IP
-	      (Intellectual Property) for a component that imposes
-	      upon the user a requirement to accept the terms of a
-	      'click-through' license.  
-              Once the license is accepted the
-	      Yocto Project build system can then build and include the
-	      corresponding component in the final BSP image.  
-              Some affected components might be essential to the normal
-	      functioning of the system and have no 'free' replacement
-	      (i.e. the resulting system would be non-functional
-	      without them).
-              On the other hand, other components might be simply
-	      'good-to-have' or purely elective, or if essential
-	      nonetheless have a 'free' (possibly less-capable)
-	      version that could be used as a in the BSP recipe.
+	      (Intellectual Property) for a component or components
+	      that impose upon the user a requirement to accept the
+	      terms of a commercial or other type of license that
+	      requires some kind of explicit EULA (End User License
+	      Agreement).  Once the license is accepted the Yocto
+	      Project build system can then build and include the
+	      corresponding component in the final BSP image, or if
+	      the BSP is available in the form of an already built
+	      image, the user will be able to download the image after
+	      agreeing to the license or EULA.
+            </para>
+            <para>
+	      Some affected components might be essential to the
+	      normal functioning of the system and have no 'free'
+	      replacement (i.e. the resulting system would be
+	      non-functional without them).  On the other hand, other
+	      components might be simply 'good-to-have' or purely
+	      elective, or if essential nonetheless have a 'free'
+	      (possibly less-capable) version that could be used as a
+	      in the BSP recipe.
             </para>
 
             <para>
-	      For cases where you can substitute something and still maintain functionality, 
-              the Yocto Project website's  
-              <ulink url='&YOCTO_HOME_URL;/download/all?keys=&amp;download_type=1&amp;download_version='>BSP Download Page</ulink> 
-              makes available 'de-featured' BSPs that are completely free of any IP encumbrances.
-              For these cases you can use the substitution directly and without any further licensing
-              requirements.  
-              If present, these fully 'de-featured' BSPs are named appropriately different 
-              as compared to the names of the respective encumbered BSPs.
-              If available, these substitutions are the simplest and most preferred options.
-              This, of course, assumes the resulting functionality meets requirements.
+	      For cases where you can substitute something and still
+              maintain functionality, the Yocto Project website's
+              <ulink url='&YOCTO_HOME_URL;/download/all?keys=&amp;download_type=1&amp;download_version='>BSP
+              Download Page</ulink> makes available 'de-featured' BSPs
+              that are completely free of any IP encumbrances.  For
+              these cases you can use the substitution directly and
+              without any further licensing requirements.  If present,
+              these fully 'de-featured' BSPs are named appropriately
+              different as compared to the names of the respective
+              encumbered BSPs.  If available, these substitutions are
+              the simplest and most preferred options.  This, of
+              course, assumes the resulting functionality meets
+              requirements.
             </para>
 
             <para>
-	      If however, a non-encumbered version is unavailable or the 'free' version 
-              would provide unsuitable functionality or quality, you can use 
-              an encumbered version.  
+	      If however, a non-encumbered version is unavailable or
+              the 'free' version would provide unsuitable
+              functionality or quality, you can use an encumbered
+              version.
             </para>
 
-            <para>  
-              Several methods exist within the Yocto Project build system to satisfy the licensing
-	      requirements for an encumbered BSP.
-              The following list describes them in preferential order:
+            <para> A couple different methods exist within the Yocto
+              Project build system to satisfy the licensing
+              requirements for an encumbered BSP.  The following list
+              describes them in order of preference:
             </para>
 
 	    <orderedlist>
             <listitem>
-
 		<para>
-		  Get a license key (or keys) for the encumbered BSP by visiting 
-                  a website and providing the name of the BSP and your email address
-                  through a web form.
+		  Yocto recipes that have commercial or other types of
+                  specially-licensed packages define a variable named
+                  LICENSE_FLAGS.  For each of those recipes, a user
+                  can specify a matching license string in a
+                  local.conf variable named LICENSE_FLAGS_WHITELIST.
+                  This signifies that the user agrees to the license,
+                  and the corresponding recipe can then be built and
+                  included in the image.  See Section 3.3.2. in The
+                  Yocto Project Reference Manual for details on these
+                  variables and how to make use of them.
                 </para>
- 
-		<para>
-		  After agreeing to any applicable license terms, the
-		  BSP key(s) will be immediately sent to the address
-		  you gave and you can use them by specifying BSPKEY_&lt;keydomain&gt;
-		  environment variables when building the image:
-		</para>
-
-		<literallayout class='monospaced'>
-     $ BSPKEY_&lt;keydomain&gt;=&lt;key&gt; bitbake core-image-sato
-		</literallayout>
 
 		<para>
-		  These steps allow the encumbered image to be built
-		  with no change at all to the normal build process.
+		  If you build as you normally would, without
+                  specifying any recipes in the
+                  LICENSE_FLAGS_WHITELIST, the build will stop and
+                  provide you with the list of recipes that you've
+                  tried to include in the image which need entries in
+                  the LICENSE_FLAGS_WHITELIST.  Once the appropriate
+                  license flags have been entered into the whitelist,
+                  restart the build to continue where it left off.
+                  During the build the prompt will not appear again
+                  since you have satisfied the requirement.
 		</para>
-
-		<para>
-		  Equivalently and probably more conveniently, a line
-		  for each key can instead be put into the user's
-		  <filename>local.conf</filename> file found in the Yocto Project file's
-                  build directory.
-		</para>
-
+ 
 		<para>
-		  The &lt;keydomain&gt; component of the
-		  BSPKEY_&lt;keydomain&gt; is required because there
-		  might be multiple licenses in effect for a given BSP.
-                  In such cases, a given &lt;keydomain&gt; corresponds to
-		  a particular license.  In order for an encumbered
-		  BSP that encompasses multiple key domains to be built
-		  successfully, a &lt;keydomain&gt; entry for each
-		  applicable license must be present in <filename>local.conf</filename> or
-		  supplied on the command-line.
+		  Once the appropriate license flags are whitelisted
+		  in the LICENSE_FLAGS_WHITELIST variable, the
+		  encumbered image can be built with no change at all
+		  to the normal build process.
 		</para>
               </listitem> 
               <listitem>
 		<para>
-		  Do nothing - build as you normally would.
-                  When a license is needed the build will stop and prompt you with instructions.
-                  Follow the license prompts that originate from the
-		  encumbered BSP.  
-                  These prompts usually take the form of instructions
-		  needed to manually fetch the encumbered package(s)
-		  and md5 sums into the required directory 
-                  (e.g. the <filename>yocto/build/downloads</filename>).
-                  Once the manual package fetch has been
-		  completed, restart the build to continue where
-		  it left off.
-                  During the build the prompt will not appear again since you have satisfied the 
-                  requirement.
-		</para>
-              </listitem>
-              <listitem>
-		<para>
-		  Get a full-featured BSP recipe rather than a key.
-                  You can do this by visiting the Yocto Project website's
-                  <ulink url='&YOCTO_HOME_URL;/download'>Download</ulink> page and 
-                  clicking on "BSP Downloads".
-		  BSP tarballs that have proprietary information can be downloaded after agreeing 
-                  to licensing requirements as part of the download process. 
-                  Obtaining the code this way allows you to build an encumbered image with 
-                  no changes at all as compared to the normal build. 
+		  Get a pre-built version of the BSP.  You can do this
+                  by visiting the Yocto Project website's
+                  <ulink url='&YOCTO_HOME_URL;/download'>Download</ulink>
+                  page and clicking on "BSP Downloads".  BSP tarballs
+                  that contain proprietary components can be
+                  downloaded after agreeing to the licensing
+                  requirements of each of the individually encumbered
+                  packages as part of the download process.  Obtaining
+                  the BSP this way allows you to access an encumbered
+                  image immediately after agreeing to the
+                  click-through license agreements presented by the
+                  website.  Note that if you want to build the image
+                  yourself using the recipes contained within the BSP
+                  tarball, you will still need to create an
+                  appropriate LICENSE_FLAGS_WHITELIST to match the
+                  encumbered recipes in the BSP.
                 </para>
               </listitem>
 	    </orderedlist>
 	    <para>
-	      Note that the third method is also the only option available
-	      when downloading pre-compiled images generated from non-free BSPs.  
-              Those images are likewise available at from the Yocto Project website.
+	      Note also that the pre-compiled images are bundled with
+	      a time-limited kernel which will run for only a
+	      predetermined amount of time (10 days) before it forces
+	      the system to reboot.  This is meant as a discouragement
+	      to directly redistributing the image as-is, and means
+	      that you'll have to eventually rebuild the image if you
+	      want to remove that restriction.
             </para> 
         </section>