From fe1b20f80a2bd1c8c19b8cdb59c04ec2095794d4 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Thu, 27 Dec 2012 14:23:23 -0600 Subject: kernel-dev: Formatted the "BSP Descriptions" section. (From yocto-docs rev: 9cfccb3372f47094479fb0a5ad095cf2b46f906e) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/kernel-dev/kernel-dev-advanced.xml | 252 +++++++++++++---------- 1 file changed, 147 insertions(+), 105 deletions(-) (limited to 'documentation') diff --git a/documentation/kernel-dev/kernel-dev-advanced.xml b/documentation/kernel-dev/kernel-dev-advanced.xml index e8587eee52..ee90df2732 100644 --- a/documentation/kernel-dev/kernel-dev-advanced.xml +++ b/documentation/kernel-dev/kernel-dev-advanced.xml @@ -1016,133 +1016,175 @@ Note: It is not strictly necessary to create a ktype scc file. The BSP file can BSP Descriptions -3.3.5 BSP Descriptions ----------- -BSP descriptions combine kernel types (see 3.3.4) with hardware-specific -features (see 3.3.3). The hardware specific portion is typically defined -independently, and then aggregated with each supported kernel type. Consider a -simple example: - -mybsp.scc: - define KMACHINE mybsp - define KTYPE standard - define KARCH i386 - - kconf mybsp.cfg - -Every BSP description should include the definition of the KMACHINE, KTYPE, and -KARCH variables. These variables allow the build-system to identify this -description as meeting the criteria set by the recipe being built. This -particular description can be said to support the "mybsp" machine for the -"standard" kernel type and the "i386" architecture. Note that there is no hard -link between the KTYPE and a ktype description file. If you do not have kernel -types defined in your meta-data, you only need to ensure that the recipe -LINUX_KERNEL_TYPE and the KTYPE here match. - -NOTE: future versions of the tooling make the specification of KTYPE in the BSP - optional. - -If you did want to separate your kernel policy from your hardware configuration, -you could do so by specifying a kernel type, such as "standard" (see 3.3.4) and -including that description in the BSP description. You might also have multiple -hardware configurations that you aggregate into a single hardware description -file which you could include here, rather than referencing a single .cfg file. -Consider the following: + BSP descriptions combine kernel types with hardware-specific + features. + The hardware specific portion is typically defined + independently, and then aggregated with each supported kernel + type. + Consider a simple example: + + mybsp.scc: + define KMACHINE mybsp + define KTYPE standard + define KARCH i386 -mybsp.scc: - define KMACHINE mybsp - define KTYPE standard - define KARCH i386 + kconf mybsp.cfg + + Every BSP description should include the definition of the + KMACHINE, KTYPE, + and KARCH variables. + These variables allow the build-system to identify this + description as meeting the criteria set by the recipe being built. + This particular description can be said to support the "mybsp" + machine for the "standard" kernel type and the "i386" architecture. + Be aware that there is no hard link between the + KTYPE and a ktype description file. + If you do not have kernel types defined in your metadata, you + only need to ensure that the recipe + LINUX_KERNEL_TYPE and the + KTYPE here match. + + Future versions of the tooling make the specification of + KTYPE in the BSP optional. + + - include standard.scc - include mybsp.scc + + If you did want to separate your kernel policy from your + hardware configuration, you could do so by specifying a kernel + type, such as "standard" (see 3.3.4) and including that + description in the BSP description. + You might also have multiple hardware configurations that you + aggregate into a single hardware description file which you + could include here, rather than referencing a single + .cfg file. + Consider the following: + + mybsp.scc: + define KMACHINE mybsp + define KTYPE standard + define KARCH i386 -In the above example standard.scc aggregates all the configuration fragments, -patches, and features that make up your standard kernel policy whereas mybsp.scc -aggregates all those necessary to support the hardware available on the mybsp -machine. For information on how to break a complete .config into the various -fragments, see 2.3.1. + include standard.scc + include mybsp.scc + + -Many real-world examples are more complex. Like any other scc file, BSP -descriptions can aggregate features. Consider the Fish River Island II (fri2) -BSP definitions from the linux-yocto-3.4 repository: + + In the above example, standard.scc + aggregates all the configuration fragments, patches, and + features that make up your standard kernel policy whereas + mybsp.scc aggregates all those necessary + to support the hardware available on the mybsp + machine. + For information on how to break a complete .config + into the various, see the + "Generating Configuration Files" + section. + -fri2.scc: - kconf hardware fri2.cfg + + Many real-world examples are more complex. + Like any other scc file, BSP + descriptions can aggregate features. + Consider the Fish River Island II (fri2) + BSP definitions from the linux-yocto-3.4 repository: + + fri2.scc: + kconf hardware fri2.cfg - include cfg/x86.scc - include features/eg20t/eg20t.scc - include cfg/dmaengine.scc - include features/ericsson-3g/f5521gw.scc - include features/power/intel.scc - include cfg/efi.scc - include features/usb/ehci-hcd.scc - include features/usb/ohci-hcd.scc - include features/iwlwifi/iwlwifi.scc - -The fri2.scc description file includes a hardware configuration fragment -(fri2.cfg) specific to the fri2 BSP as well as several more general -configuration fragments and features enabling hardware found on the fri2. This -description is then included in each of the three machine-ktype descriptions -(standard, preempt-rt, and tiny). Consider the fri2 standard description: + include cfg/x86.scc + include features/eg20t/eg20t.scc + include cfg/dmaengine.scc + nclude features/ericsson-3g/f5521gw.scc + include features/power/intel.scc + include cfg/efi.scc + include features/usb/ehci-hcd.scc + include features/usb/ohci-hcd.scc + include features/iwlwifi/iwlwifi.scc + + -fri2-standard.scc: - define KMACHINE fri2 - define KTYPE standard - define KARCH i386 + + The fri2.scc description file includes + a hardware configuration fragment + (fri2.cfg) specific to the fri2 BSP + as well as several more general configuration fragments and + features enabling hardware found on the fri2. + This description is then included in each of the three + machine-ktype descriptions (standard, preempt-rt, and tiny). + Consider the fri2 standard description: + + fri2-standard.scc: + define KMACHINE fri2 + define KTYPE standard + define KARCH i386 - include ktypes/standard/standard.scc - branch fri2 + include ktypes/standard/standard.scc + branch fri2 - git merge emgd-1.14 + git merge emgd-1.14 - include fri2.scc + include fri2.scc - # Extra fri2 configs above the minimal defined in fri2.scc - include cfg/efi-ext.scc - include features/drm-emgd/drm-emgd.scc - include cfg/vesafb.scc + # Extra fri2 configs above the minimal defined in fri2.scc + include cfg/efi-ext.scc + include features/drm-emgd/drm-emgd.scc + include cfg/vesafb.scc - # default policy for standard kernels - include cfg/usb-mass-storage.scc - -Note the "include fri2.scc" line about midway through the file. By defining all -hardware enablement common to the BSP for all kernel types, duplication is -significantly reduced. - -This description introduces a few more variables and commands worthy of further -discussion. Note the "branch" command which is used to create a -machine-specific branch into which source changes can be applied. With this -branch set up, the "git merge" command uses the git SCM to merge in a feature -branch "emgd-1.14". This could also be handled with the patch command, but for -commonly used features such as this, feature branches can be a convenient -mechanism (see 3.5). + # default policy for standard kernels + include cfg/usb-mass-storage.scc + + The "include fri2.scc" line about midway through the file defines + all hardware enablement common to the BSP for all kernel types. + Including the statement significantly reduces duplication. + -Next consider the fri2 tiny description: + + This description introduces a few more variables and commands + worthy of further discussion. + Notice the "branch" command, which is used to create a + machine-specific branch into which source changes can be applied. + With this branch set up, the git merge command + uses Git to merge in a feature branch "emgd-1.14". + This could also be handled with the patch command, but for + commonly used features such as this, feature branches can be a + convenient mechanism. + See the "Feature Branches" + section for more information. + -fri2-tiny.scc: - define KMACHINE fri2 - define KTYPE tiny - define KARCH i386 + + Now consider the Fish River Island 2 tiny + (fri2-tiny) BSP description: + + fri2-tiny.scc: + define KMACHINE fri2 + define KTYPE tiny + define KARCH i386 - include ktypes/tiny/tiny.scc - branch fri2 + include ktypes/tiny/tiny.scc + branch fri2 - include fri2.scc + include fri2.scc + + As you might expect, the tiny description includes quite a bit less. + In fact, it includes only the minimal policy defined by the + tiny ktype and the hardware-specific configuration required for + boot and the most basic functionality of the system as defined in + the base fri2 description file. + -As you might expect, the tiny description includes quite a bit less. In fact, -it includes only the minimal policy defined by the tiny ktype and the -hardware-specific configuration required for boot and the most basic -functionality of the system as defined in the base fri2 description file. Note -again the three critical variables: KMACHINE, KTYPE, and KARCH. Of these, only -the KTYPE has changed, now set to "tiny". + + Notice again the three critical variables: KMACHINE, + KTYPE, and KARCH. + Of these, only the KTYPE has changed. + It is now set to "tiny". Original text: -3.3.5 BSP Descriptions ----------- BSP descriptions combine kernel types (see 3.3.4) with hardware-specific features (see 3.3.3). The hardware specific portion is typically defined independently, and then aggregated with each supported kernel type. Consider a -- cgit v1.2.3-54-g00ecf