diff options
author | Scott Rifenbark <scott.m.rifenbark@intel.com> | 2012-12-27 14:23:23 -0600 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2013-01-16 15:59:11 +0000 |
commit | fe1b20f80a2bd1c8c19b8cdb59c04ec2095794d4 (patch) | |
tree | 3bef9ec67d42ea9ebda1be8e52ffe04dfe234723 | |
parent | d675ef08784d8bd27ac9010b8561158b97f35505 (diff) | |
download | poky-fe1b20f80a2bd1c8c19b8cdb59c04ec2095794d4.tar.gz |
kernel-dev: Formatted the "BSP Descriptions" section.
(From yocto-docs rev: 9cfccb3372f47094479fb0a5ad095cf2b46f906e)
Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r-- | documentation/kernel-dev/kernel-dev-advanced.xml | 252 |
1 files changed, 147 insertions, 105 deletions
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 | |||
1016 | <title>BSP Descriptions</title> | 1016 | <title>BSP Descriptions</title> |
1017 | 1017 | ||
1018 | <para> | 1018 | <para> |
1019 | 3.3.5 BSP Descriptions | 1019 | BSP descriptions combine kernel types with hardware-specific |
1020 | ---------- | 1020 | features. |
1021 | BSP descriptions combine kernel types (see 3.3.4) with hardware-specific | 1021 | The hardware specific portion is typically defined |
1022 | features (see 3.3.3). The hardware specific portion is typically defined | 1022 | independently, and then aggregated with each supported kernel |
1023 | independently, and then aggregated with each supported kernel type. Consider a | 1023 | type. |
1024 | simple example: | 1024 | Consider a simple example: |
1025 | 1025 | <literallayout class='monospaced'> | |
1026 | mybsp.scc: | 1026 | mybsp.scc: |
1027 | define KMACHINE mybsp | 1027 | define KMACHINE mybsp |
1028 | define KTYPE standard | 1028 | define KTYPE standard |
1029 | define KARCH i386 | 1029 | define KARCH i386 |
1030 | |||
1031 | kconf mybsp.cfg | ||
1032 | |||
1033 | Every BSP description should include the definition of the KMACHINE, KTYPE, and | ||
1034 | KARCH variables. These variables allow the build-system to identify this | ||
1035 | description as meeting the criteria set by the recipe being built. This | ||
1036 | particular description can be said to support the "mybsp" machine for the | ||
1037 | "standard" kernel type and the "i386" architecture. Note that there is no hard | ||
1038 | link between the KTYPE and a ktype description file. If you do not have kernel | ||
1039 | types defined in your meta-data, you only need to ensure that the recipe | ||
1040 | LINUX_KERNEL_TYPE and the KTYPE here match. | ||
1041 | |||
1042 | NOTE: future versions of the tooling make the specification of KTYPE in the BSP | ||
1043 | optional. | ||
1044 | |||
1045 | If you did want to separate your kernel policy from your hardware configuration, | ||
1046 | you could do so by specifying a kernel type, such as "standard" (see 3.3.4) and | ||
1047 | including that description in the BSP description. You might also have multiple | ||
1048 | hardware configurations that you aggregate into a single hardware description | ||
1049 | file which you could include here, rather than referencing a single .cfg file. | ||
1050 | Consider the following: | ||
1051 | 1030 | ||
1052 | mybsp.scc: | 1031 | kconf mybsp.cfg |
1053 | define KMACHINE mybsp | 1032 | </literallayout> |
1054 | define KTYPE standard | 1033 | Every BSP description should include the definition of the |
1055 | define KARCH i386 | 1034 | <filename>KMACHINE</filename>, <filename>KTYPE</filename>, |
1035 | and <filename>KARCH</filename> variables. | ||
1036 | These variables allow the build-system to identify this | ||
1037 | description as meeting the criteria set by the recipe being built. | ||
1038 | This particular description can be said to support the "mybsp" | ||
1039 | machine for the "standard" kernel type and the "i386" architecture. | ||
1040 | Be aware that there is no hard link between the | ||
1041 | <filename>KTYPE</filename> and a ktype description file. | ||
1042 | If you do not have kernel types defined in your metadata, you | ||
1043 | only need to ensure that the recipe | ||
1044 | <filename>LINUX_KERNEL_TYPE</filename> and the | ||
1045 | <filename>KTYPE</filename> here match. | ||
1046 | <note> | ||
1047 | Future versions of the tooling make the specification of | ||
1048 | <filename>KTYPE</filename> in the BSP optional. | ||
1049 | </note> | ||
1050 | </para> | ||
1056 | 1051 | ||
1057 | include standard.scc | 1052 | <para> |
1058 | include mybsp.scc | 1053 | If you did want to separate your kernel policy from your |
1054 | hardware configuration, you could do so by specifying a kernel | ||
1055 | type, such as "standard" (see 3.3.4) and including that | ||
1056 | description in the BSP description. | ||
1057 | You might also have multiple hardware configurations that you | ||
1058 | aggregate into a single hardware description file which you | ||
1059 | could include here, rather than referencing a single | ||
1060 | <filename>.cfg</filename> file. | ||
1061 | Consider the following: | ||
1062 | <literallayout class='monospaced'> | ||
1063 | mybsp.scc: | ||
1064 | define KMACHINE mybsp | ||
1065 | define KTYPE standard | ||
1066 | define KARCH i386 | ||
1059 | 1067 | ||
1060 | In the above example standard.scc aggregates all the configuration fragments, | 1068 | include standard.scc |
1061 | patches, and features that make up your standard kernel policy whereas mybsp.scc | 1069 | include mybsp.scc |
1062 | aggregates all those necessary to support the hardware available on the mybsp | 1070 | </literallayout> |
1063 | machine. For information on how to break a complete .config into the various | 1071 | </para> |
1064 | fragments, see 2.3.1. | ||
1065 | 1072 | ||
1066 | Many real-world examples are more complex. Like any other scc file, BSP | 1073 | <para> |
1067 | descriptions can aggregate features. Consider the Fish River Island II (fri2) | 1074 | In the above example, <filename>standard.scc</filename> |
1068 | BSP definitions from the linux-yocto-3.4 repository: | 1075 | aggregates all the configuration fragments, patches, and |
1076 | features that make up your standard kernel policy whereas | ||
1077 | <filename>mybsp.scc</filename> aggregates all those necessary | ||
1078 | to support the hardware available on the <filename>mybsp</filename> | ||
1079 | machine. | ||
1080 | For information on how to break a complete <filename>.config</filename> | ||
1081 | into the various, see the | ||
1082 | "<link linkend='generating-configuration-files'>Generating Configuration Files</link>" | ||
1083 | section. | ||
1084 | </para> | ||
1069 | 1085 | ||
1070 | fri2.scc: | 1086 | <para> |
1071 | kconf hardware fri2.cfg | 1087 | Many real-world examples are more complex. |
1088 | Like any other <filename>scc</filename> file, BSP | ||
1089 | descriptions can aggregate features. | ||
1090 | Consider the Fish River Island II (fri2) | ||
1091 | BSP definitions from the linux-yocto-3.4 repository: | ||
1092 | <literallayout class='monospaced'> | ||
1093 | fri2.scc: | ||
1094 | kconf hardware fri2.cfg | ||
1072 | 1095 | ||
1073 | include cfg/x86.scc | 1096 | include cfg/x86.scc |
1074 | include features/eg20t/eg20t.scc | 1097 | include features/eg20t/eg20t.scc |
1075 | include cfg/dmaengine.scc | 1098 | include cfg/dmaengine.scc |
1076 | include features/ericsson-3g/f5521gw.scc | 1099 | nclude features/ericsson-3g/f5521gw.scc |
1077 | include features/power/intel.scc | 1100 | include features/power/intel.scc |
1078 | include cfg/efi.scc | 1101 | include cfg/efi.scc |
1079 | include features/usb/ehci-hcd.scc | 1102 | include features/usb/ehci-hcd.scc |
1080 | include features/usb/ohci-hcd.scc | 1103 | include features/usb/ohci-hcd.scc |
1081 | include features/iwlwifi/iwlwifi.scc | 1104 | include features/iwlwifi/iwlwifi.scc |
1082 | 1105 | </literallayout> | |
1083 | The fri2.scc description file includes a hardware configuration fragment | 1106 | </para> |
1084 | (fri2.cfg) specific to the fri2 BSP as well as several more general | ||
1085 | configuration fragments and features enabling hardware found on the fri2. This | ||
1086 | description is then included in each of the three machine-ktype descriptions | ||
1087 | (standard, preempt-rt, and tiny). Consider the fri2 standard description: | ||
1088 | 1107 | ||
1089 | fri2-standard.scc: | 1108 | <para> |
1090 | define KMACHINE fri2 | 1109 | The <filename>fri2.scc</filename> description file includes |
1091 | define KTYPE standard | 1110 | a hardware configuration fragment |
1092 | define KARCH i386 | 1111 | (<filename>fri2.cfg</filename>) specific to the fri2 BSP |
1112 | as well as several more general configuration fragments and | ||
1113 | features enabling hardware found on the fri2. | ||
1114 | This description is then included in each of the three | ||
1115 | machine-ktype descriptions (standard, preempt-rt, and tiny). | ||
1116 | Consider the fri2 standard description: | ||
1117 | <literallayout class='monospaced'> | ||
1118 | fri2-standard.scc: | ||
1119 | define KMACHINE fri2 | ||
1120 | define KTYPE standard | ||
1121 | define KARCH i386 | ||
1093 | 1122 | ||
1094 | include ktypes/standard/standard.scc | 1123 | include ktypes/standard/standard.scc |
1095 | branch fri2 | 1124 | branch fri2 |
1096 | 1125 | ||
1097 | git merge emgd-1.14 | 1126 | git merge emgd-1.14 |
1098 | 1127 | ||
1099 | include fri2.scc | 1128 | include fri2.scc |
1100 | 1129 | ||
1101 | # Extra fri2 configs above the minimal defined in fri2.scc | 1130 | # Extra fri2 configs above the minimal defined in fri2.scc |
1102 | include cfg/efi-ext.scc | 1131 | include cfg/efi-ext.scc |
1103 | include features/drm-emgd/drm-emgd.scc | 1132 | include features/drm-emgd/drm-emgd.scc |
1104 | include cfg/vesafb.scc | 1133 | include cfg/vesafb.scc |
1105 | 1134 | ||
1106 | # default policy for standard kernels | 1135 | # default policy for standard kernels |
1107 | include cfg/usb-mass-storage.scc | 1136 | include cfg/usb-mass-storage.scc |
1108 | 1137 | </literallayout> | |
1109 | Note the "include fri2.scc" line about midway through the file. By defining all | 1138 | The "include fri2.scc" line about midway through the file defines |
1110 | hardware enablement common to the BSP for all kernel types, duplication is | 1139 | all hardware enablement common to the BSP for all kernel types. |
1111 | significantly reduced. | 1140 | Including the statement significantly reduces duplication. |
1112 | 1141 | </para> | |
1113 | This description introduces a few more variables and commands worthy of further | ||
1114 | discussion. Note the "branch" command which is used to create a | ||
1115 | machine-specific branch into which source changes can be applied. With this | ||
1116 | branch set up, the "git merge" command uses the git SCM to merge in a feature | ||
1117 | branch "emgd-1.14". This could also be handled with the patch command, but for | ||
1118 | commonly used features such as this, feature branches can be a convenient | ||
1119 | mechanism (see 3.5). | ||
1120 | 1142 | ||
1121 | Next consider the fri2 tiny description: | 1143 | <para> |
1144 | This description introduces a few more variables and commands | ||
1145 | worthy of further discussion. | ||
1146 | Notice the "branch" command, which is used to create a | ||
1147 | machine-specific branch into which source changes can be applied. | ||
1148 | With this branch set up, the <filename>git merge</filename> command | ||
1149 | uses Git to merge in a feature branch "emgd-1.14". | ||
1150 | This could also be handled with the patch command, but for | ||
1151 | commonly used features such as this, feature branches can be a | ||
1152 | convenient mechanism. | ||
1153 | See the "<link linkend='feature-branches'>Feature Branches</link>" | ||
1154 | section for more information. | ||
1155 | </para> | ||
1122 | 1156 | ||
1123 | fri2-tiny.scc: | 1157 | <para> |
1124 | define KMACHINE fri2 | 1158 | Now consider the Fish River Island 2 tiny |
1125 | define KTYPE tiny | 1159 | (<filename>fri2-tiny</filename>) BSP description: |
1126 | define KARCH i386 | 1160 | <literallayout class='monospaced'> |
1161 | fri2-tiny.scc: | ||
1162 | define KMACHINE fri2 | ||
1163 | define KTYPE tiny | ||
1164 | define KARCH i386 | ||
1127 | 1165 | ||
1128 | include ktypes/tiny/tiny.scc | 1166 | include ktypes/tiny/tiny.scc |
1129 | branch fri2 | 1167 | branch fri2 |
1130 | 1168 | ||
1131 | include fri2.scc | 1169 | include fri2.scc |
1170 | </literallayout> | ||
1171 | As you might expect, the tiny description includes quite a bit less. | ||
1172 | In fact, it includes only the minimal policy defined by the | ||
1173 | tiny ktype and the hardware-specific configuration required for | ||
1174 | boot and the most basic functionality of the system as defined in | ||
1175 | the base fri2 description file. | ||
1176 | </para> | ||
1132 | 1177 | ||
1133 | As you might expect, the tiny description includes quite a bit less. In fact, | 1178 | <para> |
1134 | it includes only the minimal policy defined by the tiny ktype and the | 1179 | Notice again the three critical variables: <filename>KMACHINE</filename>, |
1135 | hardware-specific configuration required for boot and the most basic | 1180 | <filename>KTYPE</filename>, and <filename>KARCH</filename>. |
1136 | functionality of the system as defined in the base fri2 description file. Note | 1181 | Of these, only the <filename>KTYPE</filename> has changed. |
1137 | again the three critical variables: KMACHINE, KTYPE, and KARCH. Of these, only | 1182 | It is now set to "tiny". |
1138 | the KTYPE has changed, now set to "tiny". | ||
1139 | </para> | 1183 | </para> |
1140 | 1184 | ||
1141 | <para> | 1185 | <para> |
1142 | Original text: | 1186 | Original text: |
1143 | <literallayout class='monospaced'> | 1187 | <literallayout class='monospaced'> |
1144 | 3.3.5 BSP Descriptions | ||
1145 | ---------- | ||
1146 | BSP descriptions combine kernel types (see 3.3.4) with hardware-specific | 1188 | BSP descriptions combine kernel types (see 3.3.4) with hardware-specific |
1147 | features (see 3.3.3). The hardware specific portion is typically defined | 1189 | features (see 3.3.3). The hardware specific portion is typically defined |
1148 | independently, and then aggregated with each supported kernel type. Consider a | 1190 | independently, and then aggregated with each supported kernel type. Consider a |