00-README: review comments v3

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

00-README

@@ -62,6 +62,13 @@ 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.
 
+When functionality is partitioned it indicates that the features kept apart
+since they won't work together (eg: schedulers (BFS vs CFS), or security
+methods (grsec vs another LSM)). Grouped functionality means that there are
+many items (features, configuration) that you want to collectively call a
+"kernel type" and validate that they work together, but there's no
+fundamental incompatibility between these features and others in the system.
+
 Note: ktypes or KTYPES are seen as "define KTYPE <name>" in .scc files, and
 are part of a BSP definition.
  
@@ -89,7 +96,7 @@ ways:
     power management.
 
   - board support: due to the source, behaviour and feature differences between
-    kernel types, they often dictate hardware/board support. A machine
+    kernel types, they often dictate hardware/board support. A BSP
     definition declares which kernel types it supports by providing
     descriptions that include a kernel type and add board support configuration
     data.
@@ -106,80 +113,117 @@ below:
     +--- tiny: base functionality + few additional features with a small footprint
 
 
-2.2 Features
-------------
+2.2 Kernel Features
+--------------------
+
+Kernel features are named containers for changes to the kernel (via patches
+and/or configuration) that implement or enable a defined feature. A feature
+can be small, or large, simple or complex, but it always represents
+functionality or behaviour that can be included by other features or kernel
+types.
 
-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.
+Within the kernel-cache, kernel features are found as $FEATURE.scc files.
 
-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 a feature contains patches, it must only be included once by a given BSP
+or kernel type, since including that feature applies a source change to the
+tree. Including it more than once 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.
+periodically contains patches, it is typically classified as a "feature". It
+should be noted, that this is only a logical distinction from Kernel
+Configuration features, 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.
+them by maintainer defined attributes such as architecture, debug, boot, etc.
 
-2.2.1 Patches
--------------
+Full kernel features are found under: kernel/* in the directory tree.
 
 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.
+tree, and do not typically contain any kernel configuration fragments.
+Configuration fragments are not required, 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 and are found under "patches/*" in
+the directory structure.
 
-2.3 Config Groups
-------------------
+2.3 Config Features
+--------------------
 
-Config groups are collections of configuration options that when included
-enable a specific behaviour or functionality. Configuration groups do not
+Config features are collections of configuration options that when included
+enable a specific behaviour or functionality. Configuration features 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.
+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.
+
+Pure Config features are found under "cfg/*" in the directory structure, and
+are named <$config_feature>.scc. 
+
+Configuration fragments are the actual input to the linux kernel 
+configuration subsystem and are included by config features. Configuration
+fragments are found throughout the tree, and are ".cfg" files.
 
 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
+can be complete or partitioned.
+
+Example:
+
+   complete.scc
+      include complete.cfg
+
+   complete.cfg
+      CONFIG_A=y
+      CONFIG_B=y
+
+   partitioned.scc
+      include partitioned_a.cfg
+      include partitioned_b.cfg
+
+   partitioned_a.cfg
+     CONFIG_A=y
+
+   partitioned_b.cfg
+     CONFIG_B=y
+
+Complete config groups contain all the options required to enable
+functionality while partitioned configurations rely on multiple includes to
+build up a set of non-overlapping options to enable functionality. In the
+preceding example, including complete.scc or partitioned.scc will result
+in the same kernel configuration.
+
+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 BSPs (Board Support Package)
+--------------------------------
+
+The BSP .scc files combine the policy from the kernel type with the
+hardware requirements of the machine into a single place. This file
+describes all the source code changes from patches and features and the
+configuration changes that are used to configure and build the kernel. 
+
+There is one BSP 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
+such, BSP 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
+BSPs 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