diff options
author | Scott Rifenbark <scott.m.rifenbark@intel.com> | 2013-01-09 14:42:50 -0800 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2013-01-16 15:59:17 +0000 |
commit | b56df9790e626683cefa8d04f3a6e7f25ac60c34 (patch) | |
tree | cff954f3209ef42ddb4425528384bcaf45fe3543 | |
parent | 03dce08b4e81fe558429aa4faadd3ac4b1e3f3ae (diff) | |
download | poky-b56df9790e626683cefa8d04f3a6e7f25ac60c34.tar.gz |
kernel-dev: Re-write of the "BSP Description" section.
First re-write of this section. Terminology is an issue here.
Dumping the term "ktype" for good.
(From yocto-docs rev: e5ee05c5bfec2a0c62b89245efbe248a66b66288)
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 | 124 |
1 files changed, 72 insertions, 52 deletions
diff --git a/documentation/kernel-dev/kernel-dev-advanced.xml b/documentation/kernel-dev/kernel-dev-advanced.xml index 4d4c850d85..d15e0100f7 100644 --- a/documentation/kernel-dev/kernel-dev-advanced.xml +++ b/documentation/kernel-dev/kernel-dev-advanced.xml | |||
@@ -1063,10 +1063,11 @@ Note: It is not strictly necessary to create a ktype scc file. The BSP file can | |||
1063 | <para> | 1063 | <para> |
1064 | BSP descriptions combine kernel types with hardware-specific | 1064 | BSP descriptions combine kernel types with hardware-specific |
1065 | features. | 1065 | features. |
1066 | The hardware specific portion is typically defined | 1066 | The hardware-specific portion is typically defined |
1067 | independently, and then aggregated with each supported kernel | 1067 | independently, and then aggregated with each supported kernel |
1068 | type. | 1068 | type. |
1069 | Consider a simple example: | 1069 | Consider this simple BSP description that supports the "mybsp" |
1070 | machine: | ||
1070 | <literallayout class='monospaced'> | 1071 | <literallayout class='monospaced'> |
1071 | mybsp.scc: | 1072 | mybsp.scc: |
1072 | define KMACHINE mybsp | 1073 | define KMACHINE mybsp |
@@ -1075,19 +1076,25 @@ Note: It is not strictly necessary to create a ktype scc file. The BSP file can | |||
1075 | 1076 | ||
1076 | kconf mybsp.cfg | 1077 | kconf mybsp.cfg |
1077 | </literallayout> | 1078 | </literallayout> |
1078 | Every BSP description should include the definition of the | 1079 | Every BSP description should define the |
1079 | <filename>KMACHINE</filename>, <filename>KTYPE</filename>, | 1080 | <filename>KMACHINE</filename>, <filename>KTYPE</filename>, |
1080 | and <filename>KARCH</filename> variables. | 1081 | and <filename>KARCH</filename> variables. |
1081 | These variables allow the build-system to identify this | 1082 | These variables allow the OpenEmbedded build system to identify |
1082 | description as meeting the criteria set by the recipe being built. | 1083 | the description as meeting the criteria set by the recipe being |
1083 | This particular description can be said to support the "mybsp" | 1084 | built. |
1084 | machine for the "standard" kernel type and the "i386" architecture. | 1085 | This simple example supports the "mybsp" machine for the "standard" |
1085 | Be aware that there is no hard link between the | 1086 | kernel and the 'i386" architecture. |
1086 | <filename>KTYPE</filename> and a ktype description file. | 1087 | </para> |
1087 | If you do not have kernel types defined in your metadata, you | 1088 | |
1088 | only need to ensure that the recipe | 1089 | <para> |
1089 | <filename>LINUX_KERNEL_TYPE</filename> and the | 1090 | Be aware that a hard link between the |
1090 | <filename>KTYPE</filename> here match. | 1091 | <filename>KTYPE</filename> variable and a kernel type |
1092 | description file does not exist. | ||
1093 | Thus, if you do not have kernel types defined in your kernel | ||
1094 | Metadata, you only need to ensure that the kernel recipe's | ||
1095 | <filename>LINUX_KERNEL_TYPE</filename> variable and the | ||
1096 | <filename>KTYPE</filename> variable in the BSP description | ||
1097 | file match. | ||
1091 | <note> | 1098 | <note> |
1092 | Future versions of the tooling make the specification of | 1099 | Future versions of the tooling make the specification of |
1093 | <filename>KTYPE</filename> in the BSP optional. | 1100 | <filename>KTYPE</filename> in the BSP optional. |
@@ -1097,12 +1104,17 @@ Note: It is not strictly necessary to create a ktype scc file. The BSP file can | |||
1097 | <para> | 1104 | <para> |
1098 | If you did want to separate your kernel policy from your | 1105 | If you did want to separate your kernel policy from your |
1099 | hardware configuration, you could do so by specifying a kernel | 1106 | hardware configuration, you could do so by specifying a kernel |
1100 | type, such as "standard" (see 3.3.4) and including that | 1107 | type, such as "standard" and including that description file |
1101 | description in the BSP description. | 1108 | in the BSP description file. |
1109 | See the "<link linkend='kernel-types'>Kernel Types</link>" section | ||
1110 | for more information. | ||
1111 | </para> | ||
1112 | |||
1113 | <para> | ||
1102 | You might also have multiple hardware configurations that you | 1114 | You might also have multiple hardware configurations that you |
1103 | aggregate into a single hardware description file which you | 1115 | aggregate into a single hardware description file that you |
1104 | could include here, rather than referencing a single | 1116 | could include in the BSP description file, rather than referencing |
1105 | <filename>.cfg</filename> file. | 1117 | a single <filename>.cfg</filename> file. |
1106 | Consider the following: | 1118 | Consider the following: |
1107 | <literallayout class='monospaced'> | 1119 | <literallayout class='monospaced'> |
1108 | mybsp.scc: | 1120 | mybsp.scc: |
@@ -1120,20 +1132,21 @@ Note: It is not strictly necessary to create a ktype scc file. The BSP file can | |||
1120 | aggregates all the configuration fragments, patches, and | 1132 | aggregates all the configuration fragments, patches, and |
1121 | features that make up your standard kernel policy whereas | 1133 | features that make up your standard kernel policy whereas |
1122 | <filename>mybsp.scc</filename> aggregates all those necessary | 1134 | <filename>mybsp.scc</filename> aggregates all those necessary |
1123 | to support the hardware available on the <filename>mybsp</filename> | 1135 | to support the hardware available on the "mybsp" machine. |
1124 | machine. | 1136 | For information on how to break a complete |
1125 | For information on how to break a complete <filename>.config</filename> | 1137 | <filename>.config</filename> file into the various |
1126 | into the various, see the | 1138 | configuration fragments, see the |
1127 | "<link linkend='generating-configuration-files'>Generating Configuration Files</link>" | 1139 | "<link linkend='generating-configuration-files'>Generating Configuration Files</link>" |
1128 | section. | 1140 | section. |
1129 | </para> | 1141 | </para> |
1130 | 1142 | ||
1131 | <para> | 1143 | <para> |
1132 | Many real-world examples are more complex. | 1144 | Many real-world examples are more complex. |
1133 | Like any other <filename>scc</filename> file, BSP | 1145 | Like any other <filename>.scc</filename> file, BSP |
1134 | descriptions can aggregate features. | 1146 | descriptions can aggregate features. |
1135 | Consider the Fish River Island II (fri2) | 1147 | Consider the Fish River Island 2 (fri2) |
1136 | BSP definitions from the linux-yocto-3.4 repository: | 1148 | BSP definition from the <filename>linux-yocto-3.4</filename> |
1149 | Git repository: | ||
1137 | <literallayout class='monospaced'> | 1150 | <literallayout class='monospaced'> |
1138 | fri2.scc: | 1151 | fri2.scc: |
1139 | kconf hardware fri2.cfg | 1152 | kconf hardware fri2.cfg |
@@ -1141,7 +1154,7 @@ Note: It is not strictly necessary to create a ktype scc file. The BSP file can | |||
1141 | include cfg/x86.scc | 1154 | include cfg/x86.scc |
1142 | include features/eg20t/eg20t.scc | 1155 | include features/eg20t/eg20t.scc |
1143 | include cfg/dmaengine.scc | 1156 | include cfg/dmaengine.scc |
1144 | nclude features/ericsson-3g/f5521gw.scc | 1157 | include features/ericsson-3g/f5521gw.scc |
1145 | include features/power/intel.scc | 1158 | include features/power/intel.scc |
1146 | include cfg/efi.scc | 1159 | include cfg/efi.scc |
1147 | include features/usb/ehci-hcd.scc | 1160 | include features/usb/ehci-hcd.scc |
@@ -1153,12 +1166,15 @@ Note: It is not strictly necessary to create a ktype scc file. The BSP file can | |||
1153 | <para> | 1166 | <para> |
1154 | The <filename>fri2.scc</filename> description file includes | 1167 | The <filename>fri2.scc</filename> description file includes |
1155 | a hardware configuration fragment | 1168 | a hardware configuration fragment |
1156 | (<filename>fri2.cfg</filename>) specific to the fri2 BSP | 1169 | (<filename>fri2.cfg</filename>) specific to the Fish River |
1157 | as well as several more general configuration fragments and | 1170 | Island 2 BSP as well as several more general configuration |
1158 | features enabling hardware found on the fri2. | 1171 | fragments and features enabling hardware found on the |
1159 | This description is then included in each of the three | 1172 | machine. |
1160 | machine-ktype descriptions (standard, preempt-rt, and tiny). | 1173 | This description file is then included in each of the three |
1161 | Consider the fri2 standard description: | 1174 | "fri2" description files for the supported kernel types |
1175 | (i.e. "standard", "preempt-rt", and "tiny"). | ||
1176 | Consider the "fri2" description for the "standard" kernel | ||
1177 | type: | ||
1162 | <literallayout class='monospaced'> | 1178 | <literallayout class='monospaced'> |
1163 | fri2-standard.scc: | 1179 | fri2-standard.scc: |
1164 | define KMACHINE fri2 | 1180 | define KMACHINE fri2 |
@@ -1180,28 +1196,30 @@ Note: It is not strictly necessary to create a ktype scc file. The BSP file can | |||
1180 | # default policy for standard kernels | 1196 | # default policy for standard kernels |
1181 | include cfg/usb-mass-storage.scc | 1197 | include cfg/usb-mass-storage.scc |
1182 | </literallayout> | 1198 | </literallayout> |
1183 | The "include fri2.scc" line about midway through the file defines | 1199 | The <filename>include</filename> command midway through the file |
1184 | all hardware enablement common to the BSP for all kernel types. | 1200 | includes the <filename>fri2.scc</filename> description that |
1185 | Including the statement significantly reduces duplication. | 1201 | defines all hardware enablement for the BSP that is common to all |
1202 | kernel types. | ||
1203 | Using this command significantly reduces duplication. | ||
1186 | </para> | 1204 | </para> |
1187 | 1205 | ||
1188 | <para> | 1206 | <para> |
1189 | This description introduces a few more variables and commands | 1207 | This "fri2" standard description introduces a few more variables |
1190 | worthy of further discussion. | 1208 | and commands that are worth further discussion. |
1191 | Notice the "branch" command, which is used to create a | 1209 | Notice the <filename>branch fri2</filename> command, which creates |
1192 | machine-specific branch into which source changes can be applied. | 1210 | a machine-specific branch into which source changes are applied. |
1193 | With this branch set up, the <filename>git merge</filename> command | 1211 | With this branch set up, the <filename>git merge</filename> command |
1194 | uses Git to merge in a feature branch "emgd-1.14". | 1212 | uses Git to merge in a feature branch named "emgd-1.14". |
1195 | This could also be handled with the patch command, but for | 1213 | You could also handle this with the <filename>patch</filename> |
1196 | commonly used features such as this, feature branches can be a | 1214 | command. |
1197 | convenient mechanism. | 1215 | However, for commonly used features such as this, feature branches |
1216 | are a convenient mechanism. | ||
1198 | See the "<link linkend='feature-branches'>Feature Branches</link>" | 1217 | See the "<link linkend='feature-branches'>Feature Branches</link>" |
1199 | section for more information. | 1218 | section for more information. |
1200 | </para> | 1219 | </para> |
1201 | 1220 | ||
1202 | <para> | 1221 | <para> |
1203 | Now consider the Fish River Island 2 tiny | 1222 | Now consider the "fri2" description for the "tiny" kernel type: |
1204 | (<filename>fri2-tiny</filename>) BSP description: | ||
1205 | <literallayout class='monospaced'> | 1223 | <literallayout class='monospaced'> |
1206 | fri2-tiny.scc: | 1224 | fri2-tiny.scc: |
1207 | define KMACHINE fri2 | 1225 | define KMACHINE fri2 |
@@ -1213,17 +1231,19 @@ Note: It is not strictly necessary to create a ktype scc file. The BSP file can | |||
1213 | 1231 | ||
1214 | include fri2.scc | 1232 | include fri2.scc |
1215 | </literallayout> | 1233 | </literallayout> |
1216 | As you might expect, the tiny description includes quite a bit less. | 1234 | As you might expect, the "tiny" description includes quite a |
1235 | bit less. | ||
1217 | In fact, it includes only the minimal policy defined by the | 1236 | In fact, it includes only the minimal policy defined by the |
1218 | tiny ktype and the hardware-specific configuration required for | 1237 | "tiny" kernel type and the hardware-specific configuration required |
1219 | boot and the most basic functionality of the system as defined in | 1238 | for booting the machine along with the most basic functionality of |
1220 | the base fri2 description file. | 1239 | the system as defined in the base "fri2" description file. |
1221 | </para> | 1240 | </para> |
1222 | 1241 | ||
1223 | <para> | 1242 | <para> |
1224 | Notice again the three critical variables: <filename>KMACHINE</filename>, | 1243 | Notice again the three critical variables: |
1225 | <filename>KTYPE</filename>, and <filename>KARCH</filename>. | 1244 | <filename>KMACHINE</filename>, <filename>KTYPE</filename>, |
1226 | Of these, only the <filename>KTYPE</filename> has changed. | 1245 | and <filename>KARCH</filename>. |
1246 | Of these variables, only the <filename>KTYPE</filename> has changed. | ||
1227 | It is now set to "tiny". | 1247 | It is now set to "tiny". |
1228 | </para> | 1248 | </para> |
1229 | 1249 | ||