[yocto] [PATCH 1/5] dev-manual: Add 'Creating Partitioned Images/Plugins' subsection

[Tom Zanussi]

Add a new section discussing plugins, taken directly from the
corresponding wic help section.

Signed-off-by: Tom Zanussi <tom.zanussi at linux.intel.com>
---
 .../dev-manual/dev-manual-common-tasks.xml         | 158 +++++++++++++++++++++
 1 file changed, 158 insertions(+)

diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index c4c3d9f..c3df8b3 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -3916,6 +3916,164 @@
             </section>
         </section>
 
+        <section id='openembedded-kickstart-plugins'>
+            <title>Plugins</title>
+
+            <para>
+	      Plugins allow <filename>wic</filename> functionality to
+	      be extended and specialized by users.  This section
+	      documents the plugin interface, which is currently
+	      restricted to 'source' plugins.
+            </para>
+
+            <para>
+	      'Source' plugins provide a mechanism to customize
+	      various aspects of the image generation process in
+	      <filename>wic</filename>, mainly the contents of
+	      partitions.
+            </para>
+
+            <para>
+	      Source plugins provide a mechanism for mapping values
+	      specified in <filename>.wks</filename> files using the
+	      <filename>--source</filename> keyword to a particular
+	      plugin implementation that populates a corresponding
+	      partition.
+            </para>
+
+            <para>
+	      A source plugin is created as a subclass of
+	      <filename>SourcePlugin</filename> (see
+	      <filename>scripts/lib/mic/pluginbase.py</filename>) and
+	      the plugin file containing it is added to
+	      <filename>scripts/lib/mic/plugins/source/</filename> to
+	      make the plugin implementation available to the
+	      <filename>wic</filename> implementation.
+            </para>
+
+            <para>
+	      Source plugins can also be implemented and added by
+	      external layers - any plugins found in a
+	      <filename>scripts/lib/mic/plugins/source/</filename>
+	      directory in an external layer will also be made
+	      available.
+            </para>
+
+            <para>
+	      When the <filename>wic</filename> implementation needs
+	      to invoke a partition-specific implementation, it looks
+	      for the plugin that has the same name as the
+	      <filename>--source</filename> param given to that
+	      partition.  For example, if the partition is set up like
+	      this:
+            </para>
+
+            <para>
+                <literallayout class='monospaced'>
+     part /boot --source bootimg-pcbios   ...
+                </literallayout>
+            </para>
+
+            <para>
+	      then the methods defined as class members of the plugin
+	      having the matching <filename>bootimg-pcbios
+	      .name</filename> class member would be used.
+            </para>
+
+            <para>
+	      To be more concrete, here's the plugin definition that
+	      would match a <filename>'--source
+	      bootimg-pcbios'</filename> usage, along with an example
+	      method that would be called by the
+	      <filename>wic</filename> implementation when it needed
+	      to invoke an implementation-specific
+	      partition-preparation function:
+            </para>
+
+            <para>
+                <literallayout class='monospaced'>
+    class BootimgPcbiosPlugin(SourcePlugin):
+        name = 'bootimg-pcbios'
+
+    @classmethod
+        def do_prepare_partition(self, part, ...)
+                </literallayout>
+            </para>
+
+            <para>
+	      If the subclass itself doesn't implement a function, a
+	      'default' version in a superclass will be located and
+	      used, which is why all plugins must be derived from
+	      <filename>SourcePlugin</filename>.
+            </para>
+
+            <para>
+	      The <filename>SourcePlugin</filename> class defines the
+	      following methods, which is the current set of methods
+	      that can be implemented/overridden by
+	      <filename>--source</filename> plugins.  Any methods not
+	      implemented by a <filename>SourcePlugin</filename>
+	      subclass inherit the implementations present in the
+	      <filename>SourcePlugin</filename> class (see the
+	      <filename>SourcePlugin</filename> source for details):
+            </para>
+
+            <para>
+            <itemizedlist>
+                <listitem><para><emphasis><filename>do_prepare_partition()</filename>:</emphasis>
+                Called to do the actual content population for a
+                partition.  In other words, it 'prepares' the final
+                partition image which will be incorporated into the
+                disk image.  </para></listitem>
+
+                <listitem><para><emphasis><filename>do_configure_partition()</filename>:</emphasis>
+                Called before
+                <filename>do_prepare_partition()</filename>, typically
+                used to create custom configuration files for a
+                partition, for example syslinux or grub config files.
+                </para></listitem>
+
+                <listitem><para><emphasis><filename>do_install_disk()</filename>:</emphasis>
+                Called after all partitions have been prepared and
+                assembled into a disk image.  This provides a hook to
+                allow finalization of a disk image, for example to
+                write an MBR to it.  </para></listitem>
+
+                <listitem><para><emphasis><filename>do_stage_partition()</filename>:</emphasis>
+                Special content-staging hook called before
+                <filename>do_prepare_partition()</filename>, normally
+                empty.
+                <para>
+		  Typically, a partition will just use the passed-in
+		  parameters, for example the unmodified value of
+		  <filename>bootimg_dir</filename>.  In some cases,
+		  however, things may need to be more tailored.  As an
+		  example, certain files may additionally need to be
+		  taken from <filename>bootimg_dir + /boot</filename>.
+		  This hook allows those files to be staged in a
+		  customized fashion.  Note that
+		  <filename>get_bitbake_var()</filename> allows you to
+		  access non-standard variables that you might want to
+		  use for this.
+		</para>
+		</para></listitem>
+             </itemizedlist>
+            </para>
+
+            <para>
+	      This scheme is extensible - adding more hooks is a
+	      simple matter of adding more plugin methods to
+	      <filename>SourcePlugin</filename> and derived classes.
+	      The code that then needs to call the plugin methods uses
+	      <filename>plugin.get_source_plugin_methods()</filename>
+	      to find the method(s) needed by the call; this is done
+	      by filling up a dict with keys containing the method
+	      names of interest - on success, these will be filled in
+	      with the actual methods. Please see the implementation
+	      for examples and details.
+            </para>
+        </section>
+
         <section id='openembedded-kickstart-wks-reference'>
             <title>OpenEmbedded Kickstart (.wks) Reference</title>
 
-- 
1.8.3.1