summaryrefslogtreecommitdiffstats
path: root/documentation/kernel-dev/kernel-dev-advanced.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/kernel-dev/kernel-dev-advanced.xml')
-rw-r--r--documentation/kernel-dev/kernel-dev-advanced.xml390
1 files changed, 390 insertions, 0 deletions
diff --git a/documentation/kernel-dev/kernel-dev-advanced.xml b/documentation/kernel-dev/kernel-dev-advanced.xml
index 9872bf6859..e8587eee52 100644
--- a/documentation/kernel-dev/kernel-dev-advanced.xml
+++ b/documentation/kernel-dev/kernel-dev-advanced.xml
@@ -871,9 +871,399 @@ will want to specify in the KERNEL_FEATURES variable of the Linux kernel recipe
871 </para> 871 </para>
872 </section> 872 </section>
873 873
874 <section id='kernel-types'>
875 <title>Kernel Types</title>
874 876
877 <para>
878 Kernel types, or <filename>ktypes</filename>, are used to
879 aggregate all non-hardware configuration fragments together
880 with any patches you want to use for all Linux kernel builds
881 of the specified <filename>ktype</filename>.
882 In short, <filename>ktypes</filename> are where you define a
883 high-level kernel policy.
884 Syntactically, however, they are no different than features
885 as described in the previous section.
886 The <filename>ktype</filename> is selected by the
887 <filename>LINUX_KERNEL_TYPE</filename> variable in the recipe.
888 See the "<link linkend='using-metadata-in-a-recipe'>Using Metadata in a Recipe</link>"
889 section for more information.
890 </para>
891
892 <para>
893 By way of example, the linux-yocto-3.4 tree defines three
894 <filename>ktypes</filename>: standard, tiny, and preempt-rt.
895 <itemizedlist>
896 <listitem><para>standard:
897 Includes the generic Linux kernel
898 policy of the Yocto Project linux-yocto kernel recipes.
899 This includes things like which file systems, which
900 networking options, which core kernel features, and which
901 debugging and tracing options are supported.
902 </para></listitem>
903 <listitem><para>preempt-rt:
904 Applies the <filename>PREEMPT_RT</filename>
905 patches and the configuration options required to
906 build a real-time Linux kernel.
907 It inherits from standard.</para></listitem>
908 <listitem><para>tiny:
909 Independent from the standard configuration
910 and defines a bare minimum configuration meant to serve as a
911 base for very small Linux kernels.
912 Tiny does not currently include any source changes, but it
913 might in the future.</para></listitem>
914 </itemizedlist>
915 </para>
916
917 <para>
918 The standard kernel type is defined by
919 <filename>standard.scc</filename>:
920 <literallayout class='monospaced'>
921 # Include this kernel type fragment to get the standard features and
922 # configuration values.
923
924 # Include all standard features
925 include standard-nocfg.scc
926
927 kconf non-hardware standard.cfg
928
929 # individual cfg block section
930 include cfg/fs/devtmpfs.scc
931 include cfg/fs/debugfs.scc
932 include cfg/fs/btrfs.scc
933 include cfg/fs/ext2.scc
934 include cfg/fs/ext3.scc
935 include cfg/fs/ext4.scc
936
937 include cfg/net/ipv6.scc
938 include cfg/net/ip_nf.scc
939 include cfg/net/ip6_nf.scc
940 include cfg/net/bridge.scc
941 </literallayout>
942 </para>
943
944 <para>
945 As with any <filename>scc</filename> file, a
946 <filename>ktype</filename> definition can aggregate other
947 <filename>scc</filename> files with the
948 <filename>include</filename> command, or directly pull in
949 configuration fragments and patches with the
950 <filename>kconf</filename> and <filename>patch</filename>
951 commands, respectively.
952 </para>
953
954 <note>
955 It is not strictly necessary to create a
956 <filename>ktype scc</filename> file.
957 The BSP file can define the <filename>ktype</filename> implicitly
958 with a <filename>define KTYPE myktype</filename> line. See the
959 next section for more information.
960 </note>
875 961
962 <para>
963 Original text:
964 <literallayout class='monospaced'>
965Kernel types, or ktypes, are used to aggregate all non-hardware configuration
966fragments together with any patches you want to use for all Linux kernel builds
967of the specified ktype. In short, ktypes are where you define a high-level
968kernel policy. Syntactically, however, they are no different than features (see
9693.3.3). preempt-rt, and tiny. The ktype is selected by the LINUX_KERNEL_TYPE
970variable in the recipe (see 3.1).
971
972By way of example, the linux-yocto-3.4 tree defines three ktypes: standard,
973tiny, and preempt-rt. The standard kernel type includes the generic Linux kernel
974policy of the Yocto Project linux-yocto kernel recipes. This includes things
975like which filesystems, which networking options, which core kernel features,
976and which debugging and tracing optoins are supported. The preempt-rt kernel
977type applies the PREEMPT_RT patches and the configuration options required to
978build a real-time Linux kernel. It inherits from standard. The tiny kernel type
979is independent from the standard configuration and defines a bare minimum
980configuration meant to serve as a base for very small Linux kernels. Tiny does
981not currently include any source changes, but it may in the future.
982
983The standard ktype is defined by standard.scc:
984 # Include this kernel type fragment to get the standard features and
985 # configuration values.
986
987 # Include all standard features
988 include standard-nocfg.scc
989
990 kconf non-hardware standard.cfg
991
992 # individual cfg block section
993 include cfg/fs/devtmpfs.scc
994 include cfg/fs/debugfs.scc
995 include cfg/fs/btrfs.scc
996 include cfg/fs/ext2.scc
997 include cfg/fs/ext3.scc
998 include cfg/fs/ext4.scc
999
1000 include cfg/net/ipv6.scc
1001 include cfg/net/ip_nf.scc
1002 include cfg/net/ip6_nf.scc
1003 include cfg/net/bridge.scc
1004
1005As with any scc file, a ktype definition can aggregate other scc files with the
1006include command, or directly pull in configuration fragments and patches with
1007the kconf and patch commands, respectively.
1008
1009Note: It is not strictly necessary to create a ktype scc file. The BSP file can
1010 define the ktype implicitly with a "define KTYPE myktype" line. See 3.3.5.
1011 </literallayout>
1012 </para>
1013 </section>
876 1014
1015 <section id='bsp-descriptions'>
1016 <title>BSP Descriptions</title>
1017
1018 <para>
10193.3.5 BSP Descriptions
1020----------
1021BSP descriptions combine kernel types (see 3.3.4) with hardware-specific
1022features (see 3.3.3). The hardware specific portion is typically defined
1023independently, and then aggregated with each supported kernel type. Consider a
1024simple example:
1025
1026mybsp.scc:
1027 define KMACHINE mybsp
1028 define KTYPE standard
1029 define KARCH i386
1030
1031 kconf mybsp.cfg
1032
1033Every BSP description should include the definition of the KMACHINE, KTYPE, and
1034KARCH variables. These variables allow the build-system to identify this
1035description as meeting the criteria set by the recipe being built. This
1036particular 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
1038link between the KTYPE and a ktype description file. If you do not have kernel
1039types defined in your meta-data, you only need to ensure that the recipe
1040LINUX_KERNEL_TYPE and the KTYPE here match.
1041
1042NOTE: future versions of the tooling make the specification of KTYPE in the BSP
1043 optional.
1044
1045If you did want to separate your kernel policy from your hardware configuration,
1046you could do so by specifying a kernel type, such as "standard" (see 3.3.4) and
1047including that description in the BSP description. You might also have multiple
1048hardware configurations that you aggregate into a single hardware description
1049file which you could include here, rather than referencing a single .cfg file.
1050Consider the following:
1051
1052mybsp.scc:
1053 define KMACHINE mybsp
1054 define KTYPE standard
1055 define KARCH i386
1056
1057 include standard.scc
1058 include mybsp.scc
1059
1060In the above example standard.scc aggregates all the configuration fragments,
1061patches, and features that make up your standard kernel policy whereas mybsp.scc
1062aggregates all those necessary to support the hardware available on the mybsp
1063machine. For information on how to break a complete .config into the various
1064fragments, see 2.3.1.
1065
1066Many real-world examples are more complex. Like any other scc file, BSP
1067descriptions can aggregate features. Consider the Fish River Island II (fri2)
1068BSP definitions from the linux-yocto-3.4 repository:
1069
1070fri2.scc:
1071 kconf hardware fri2.cfg
1072
1073 include cfg/x86.scc
1074 include features/eg20t/eg20t.scc
1075 include cfg/dmaengine.scc
1076 include features/ericsson-3g/f5521gw.scc
1077 include features/power/intel.scc
1078 include cfg/efi.scc
1079 include features/usb/ehci-hcd.scc
1080 include features/usb/ohci-hcd.scc
1081 include features/iwlwifi/iwlwifi.scc
1082
1083The fri2.scc description file includes a hardware configuration fragment
1084(fri2.cfg) specific to the fri2 BSP as well as several more general
1085configuration fragments and features enabling hardware found on the fri2. This
1086description is then included in each of the three machine-ktype descriptions
1087(standard, preempt-rt, and tiny). Consider the fri2 standard description:
1088
1089fri2-standard.scc:
1090 define KMACHINE fri2
1091 define KTYPE standard
1092 define KARCH i386
1093
1094 include ktypes/standard/standard.scc
1095 branch fri2
1096
1097 git merge emgd-1.14
1098
1099 include fri2.scc
1100
1101 # Extra fri2 configs above the minimal defined in fri2.scc
1102 include cfg/efi-ext.scc
1103 include features/drm-emgd/drm-emgd.scc
1104 include cfg/vesafb.scc
1105
1106 # default policy for standard kernels
1107 include cfg/usb-mass-storage.scc
1108
1109Note the "include fri2.scc" line about midway through the file. By defining all
1110hardware enablement common to the BSP for all kernel types, duplication is
1111significantly reduced.
1112
1113This description introduces a few more variables and commands worthy of further
1114discussion. Note the "branch" command which is used to create a
1115machine-specific branch into which source changes can be applied. With this
1116branch set up, the "git merge" command uses the git SCM to merge in a feature
1117branch "emgd-1.14". This could also be handled with the patch command, but for
1118commonly used features such as this, feature branches can be a convenient
1119mechanism (see 3.5).
1120
1121Next consider the fri2 tiny description:
1122
1123fri2-tiny.scc:
1124 define KMACHINE fri2
1125 define KTYPE tiny
1126 define KARCH i386
1127
1128 include ktypes/tiny/tiny.scc
1129 branch fri2
1130
1131 include fri2.scc
1132
1133As you might expect, the tiny description includes quite a bit less. In fact,
1134it includes only the minimal policy defined by the tiny ktype and the
1135hardware-specific configuration required for boot and the most basic
1136functionality of the system as defined in the base fri2 description file. Note
1137again the three critical variables: KMACHINE, KTYPE, and KARCH. Of these, only
1138the KTYPE has changed, now set to "tiny".
1139 </para>
1140
1141 <para>
1142 Original text:
1143 <literallayout class='monospaced'>
11443.3.5 BSP Descriptions
1145----------
1146BSP descriptions combine kernel types (see 3.3.4) with hardware-specific
1147features (see 3.3.3). The hardware specific portion is typically defined
1148independently, and then aggregated with each supported kernel type. Consider a
1149simple example:
1150
1151mybsp.scc:
1152 define KMACHINE mybsp
1153 define KTYPE standard
1154 define KARCH i386
1155
1156 kconf mybsp.cfg
1157
1158Every BSP description should include the definition of the KMACHINE, KTYPE, and
1159KARCH variables. These variables allow the build-system to identify this
1160description as meeting the criteria set by the recipe being built. This
1161particular description can be said to support the "mybsp" machine for the
1162"standard" kernel type and the "i386" architecture. Note that there is no hard
1163link between the KTYPE and a ktype description file. If you do not have kernel
1164types defined in your meta-data, you only need to ensure that the recipe
1165LINUX_KERNEL_TYPE and the KTYPE here match.
1166
1167NOTE: future versions of the tooling make the specification of KTYPE in the BSP
1168 optional.
1169
1170If you did want to separate your kernel policy from your hardware configuration,
1171you could do so by specifying a kernel type, such as "standard" (see 3.3.4) and
1172including that description in the BSP description. You might also have multiple
1173hardware configurations that you aggregate into a single hardware description
1174file which you could include here, rather than referencing a single .cfg file.
1175Consider the following:
1176
1177mybsp.scc:
1178 define KMACHINE mybsp
1179 define KTYPE standard
1180 define KARCH i386
1181
1182 include standard.scc
1183 include mybsp.scc
1184
1185In the above example standard.scc aggregates all the configuration fragments,
1186patches, and features that make up your standard kernel policy whereas mybsp.scc
1187aggregates all those necessary to support the hardware available on the mybsp
1188machine. For information on how to break a complete .config into the various
1189fragments, see 2.3.1.
1190
1191Many real-world examples are more complex. Like any other scc file, BSP
1192descriptions can aggregate features. Consider the Fish River Island II (fri2)
1193BSP definitions from the linux-yocto-3.4 repository:
1194
1195fri2.scc:
1196 kconf hardware fri2.cfg
1197
1198 include cfg/x86.scc
1199 include features/eg20t/eg20t.scc
1200 include cfg/dmaengine.scc
1201 include features/ericsson-3g/f5521gw.scc
1202 include features/power/intel.scc
1203 include cfg/efi.scc
1204 include features/usb/ehci-hcd.scc
1205 include features/usb/ohci-hcd.scc
1206 include features/iwlwifi/iwlwifi.scc
1207
1208The fri2.scc description file includes a hardware configuration fragment
1209(fri2.cfg) specific to the fri2 BSP as well as several more general
1210configuration fragments and features enabling hardware found on the fri2. This
1211description is then included in each of the three machine-ktype descriptions
1212(standard, preempt-rt, and tiny). Consider the fri2 standard description:
1213
1214fri2-standard.scc:
1215 define KMACHINE fri2
1216 define KTYPE standard
1217 define KARCH i386
1218
1219 include ktypes/standard/standard.scc
1220 branch fri2
1221
1222 git merge emgd-1.14
1223
1224 include fri2.scc
1225
1226 # Extra fri2 configs above the minimal defined in fri2.scc
1227 include cfg/efi-ext.scc
1228 include features/drm-emgd/drm-emgd.scc
1229 include cfg/vesafb.scc
1230
1231 # default policy for standard kernels
1232 include cfg/usb-mass-storage.scc
1233
1234Note the "include fri2.scc" line about midway through the file. By defining all
1235hardware enablement common to the BSP for all kernel types, duplication is
1236significantly reduced.
1237
1238This description introduces a few more variables and commands worthy of further
1239discussion. Note the "branch" command which is used to create a
1240machine-specific branch into which source changes can be applied. With this
1241branch set up, the "git merge" command uses the git SCM to merge in a feature
1242branch "emgd-1.14". This could also be handled with the patch command, but for
1243commonly used features such as this, feature branches can be a convenient
1244mechanism (see 3.5).
1245
1246Next consider the fri2 tiny description:
1247
1248fri2-tiny.scc:
1249 define KMACHINE fri2
1250 define KTYPE tiny
1251 define KARCH i386
1252
1253 include ktypes/tiny/tiny.scc
1254 branch fri2
1255
1256 include fri2.scc
1257
1258As you might expect, the tiny description includes quite a bit less. In fact,
1259it includes only the minimal policy defined by the tiny ktype and the
1260hardware-specific configuration required for boot and the most basic
1261functionality of the system as defined in the base fri2 description file. Note
1262again the three critical variables: KMACHINE, KTYPE, and KARCH. Of these, only
1263the KTYPE has changed, now set to "tiny".
1264 </literallayout>
1265 </para>
1266 </section>
877</section> 1267</section>
878 1268
879</chapter> 1269</chapter>