00-README: correct and clarifications

Updating the 00-README with fixes and updates from Darren Hart's
review of the initial patch.

Signed-off-by: Bruce Ashfield <bruce.ashfield@windriver.com>

00-README

+1.0 Overview
+============
 
-This is the cache of the kernel patches for the "next" kernel layer.
+The linux-yocto kernel is composed of additions/modifications to the
+kernel.org source, plus configuration/control data to manage and use those
+changes.
+
+Source code changes are seen as git commits to the kernel source tree, are
+arranged into features (sometimes) separated by branches and marked by tags.
+
+The configuration and control data is contained within a separate branch from
+source changes called the meta branch. The configuration data is contained
+within the kernel-cache directory structure, and represents the instructions
+to modify the source tree and the configuration policies required to configure
+and build the kernel.
+
+While changes to the source code have already been applied to the tree, the
+control and configuration data is used before and during the kernel build
+process to generate a valid kernel config.
+
+This README explains the configuration data and policies around the
+organization of this information, it is not a guide to tree construction, scc
+file syntax or linux-yocto architecture.
+
+2.0 Configuration Policy
+========================
+
+The configuration data contained within the meta branch has the following
+purposes:
+
+  - Documents and defines hardware, non-hardware, required and optional
+    configuration data that are used to keep software configuration policy
+    and board support configuration separate. It also tags configuration data
+    in a manner that an audit can be performed to ensure that polices make it
+    to the final .config and that required options are not overridden or
+    dropped from the final .config.
+
+  - Creates a baseline configuration that can be inherited/included to result
+    in consistent configuration across all derived kernel builds
+
+  - Groups patches and their configuration data into documented features. The
+    proper configuration and enablement of a kernel change is coupled with the
+    patches that make the change to the source.
+
+  - Creates named feature fragments that when included enable the required
+    options to implement a specific behaviour (i.e. USB boot)
+
+  - Defines BSPs (Board Support Packages) (machines) that select a policy
+    (features + config) and hardware options to form a buildable, bootable
+    configuration.
+
+The policies that are contained within the meta branch can be overridden by
+external descriptions using the same description format as the meta branch
+configuration. This allows for flexible modification and extension of the
+base policy. Also, if a previously defined BSP configuration is modified, it
+can be audited against the software policy to generate a compliance report.
+
+2.1 Kernel Types (ktypes)
+-------------------------
+
+Kernel types (ktypes) are the highest level policy containers and represent
+a significant set of kernel functionality that has been grouped (and named)
+or partitioned.
+
+Note: ktypes or KTYPES are seen as "define KTYPE <name>" in .scc files, and
+are part of a BSP definition.
+ 
+There are often significant differences between kernel types in the following
+ways:
+
+  - source code: large or invasive features that cannot be cleanly disabled, 
+    or that cannot co-exist with other features at a source code level are 
+    separated by kernel type. The preempt-rt patches, alternate schedulers,
+    grsecurity, are some examples of patches that are important parts of 
+    kernel type definition.
+
+  - behaviour: A kernel type defines a default behaviour, which is often a
+    trade off against other options. 
+
+       - performance vs. determinism
+       - security vs. flexibility
+       - size vs features
+       - ...
+
+    are all common parts of behavioural differences between kernel types.
+
+  - feature support: different kernel types support different sets of features,
+    such as XIP or different block schedulers, tracers, network devices and 
+    power management.
+
+  - board support: due to the source, behaviour and feature differences between
+    kernel types, they often dictate hardware/board support. A machine
+    definition declares which kernel types it supports by providing
+    descriptions that include a kernel type and add board support configuration
+    data.
+
+Kernel types can be inherited and extended. An example inheritance tree is
+below:
+
+  base: common/basic functionality, upstream features and bug fixes
+    |
+    +--- standard: selected functionality and performance profile.
+    |       |
+    |       +--- preempt-rt: real time extensions for the base + standard
+    |
+    +--- tiny: base functionality + few additional features with a small footprint
+
+
+2.2 Features
+------------
+
+Kernel features are containers for changes to the kernel via patches and
+configuration that implement a specific behaviour. A feature can be small, or
+large, simple or complex, but it always represents functionality that can be
+included by other features or kernel types.
+
+If a feature contains patches, it must only be included once by a given 
+BSP or kernel type, since including it modifies the tree and would result in
+the double application of the same patches, which will fail.
+
+If functionality is added via patches, is frequently extended by patches, or
+periodically contains patches, it is classified as a "feature". It should be
+noted, that this is only a logical distinction from config groups, since the
+underlying mechanism is the same.
+
+Features are often sub-categorized into a directory structure that groups
+them by user defined attributes such as architecture, debug, boot, etc.
+
+2.2.1 Patches
+-------------
+
+Patches are a feature subtype and are simply a grouping of changes into a
+named category. These typically are included by kernel types, and are not
+meant to implement a defined functionality or be included multiple times.
+
+These often contain bug fixes, backports or other small changes to the kernel
+tree, and do not typically contain any kernel configuration fragments, since
+they are fixing bugs, or adding simple functionality that does not need
+Kconfig options to be enabled. Patches are normally arranged into a directory
+structure that makes their maintenance and carry forward easier.
+
+2.3 Config Groups
+------------------
+
+Config groups are collections of configuration options that when included
+enable a specific behaviour or functionality. Configuration groups do not
+contain patches, and can be included multiple times by any other feature or
+kernel type. The impact of configuration groups is additive, and order
+matters, since the last included config group can override the behaviour of
+previous includes.
+
+Note: Depending on the architecture of the meta data, configuration groups
+can be complete, or partitioned. Complete config groups contain all the
+options required to enable functionality, partitioned configurations rely on
+multiple includes to build up a set of non-overlapping options to enable
+functionality.  Complete groups are simpler to include, but make it more
+difficult to remove or disable an option (since it can appear multiple
+times), while partitioned configuration only has a single option in a single
+config group, but make it more difficult to determine the right set of groups
+to include for the desired functionality.
+
+2.4 Machine / BSP
+-----------------
+
+The machine is the top-level description of a board, and the hardware that it
+supports. A machine/BSP .scc file is found by a build system to start the
+processing of a particular machine and kernel type combination. From the
+machine description, all the source code changes (patches, features) and
+configuration changes that are used to configure and build the kernel are
+located.
+
+There is one machine description per kernel type that is located by a build
+system when it starts the process of configuring and build a kernel for a
+board.
+
+To repeat an earlier point, one of the goals of the data in the meta branch
+is the separation between software policy and board support configuration. As
+such, machine descriptions should set configuration options that are related
+to physical devices (drivers, driver options, flash filesystems, error
+checking, etc) and leave software policy to features or kernel types.
+
+Machines directly include kernel types to inherit their functionality.  They
+include feature and config fragments to define non-hardware configuration and
+functionality. New or local configuration values introduced by a BSP should
+not override non-hardware (or policy) values unless absolutely necessary, but
+always should define the hardware they support.
+
+2.5 Staged Features
+-------------------
+
+It is often desirable to manage some features independently from other
+features in the tree to allow clean upstream fix integration and to avoid
+managing large numbers of patches and contributions. These branches are
+called "staged" features, and are included by BSP definitions by merging the
+topic branch in their board description.
+
+    git merge emgd-1.14
+
+is an example of merging a staged emgd feature into a BSP branch via a git
+operation.
+
+2.6 References
+--------------
+
+  git://git.yoctoproject.org/yocto-kernel-cache