diff --git a/00-README b/00-README index 23518b4da4df7fc98849f1e8007595cd6a374299..bef99b5dc52489d162f226aeac5055a25f898a5a 100644 --- a/00-README +++ b/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