summaryrefslogtreecommitdiffstats
path: root/documentation/kernel-manual
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/kernel-manual')
-rw-r--r--documentation/kernel-manual/kernel-how-to.xml277
1 files changed, 49 insertions, 228 deletions
diff --git a/documentation/kernel-manual/kernel-how-to.xml b/documentation/kernel-manual/kernel-how-to.xml
index 8ef9793c60..bce2c2ce44 100644
--- a/documentation/kernel-manual/kernel-how-to.xml
+++ b/documentation/kernel-manual/kernel-how-to.xml
@@ -1010,240 +1010,60 @@ That's it. Configure and build.
1010 <title>Creating a BSP Based on an Existing Similar BSP</title> 1010 <title>Creating a BSP Based on an Existing Similar BSP</title>
1011 1011
1012 <para> 1012 <para>
1013 This section provides an example for creating a BSP that is based on an existing, and hopefully, 1013 This section overviews the process of creating a BSP based on an
1014 similar one. 1014 existing similar BSP.
1015 The example assumes you will be using a local kernel repository and you will be pointing the 1015 The information is introductory in nature and does not provide step-by-step examples.
1016 kernel recipes at that repository. 1016 For detailed information on how to create a BSP given an existing similar BSP
1017 Follow the steps in this section and keep in mind your particular situation and differences. 1017 see the Yocto Project Development Manual [NEED LINK] or the
1018 <ulink url='https://wiki.yoctoproject.org/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'></ulink>
1019 wiki page.
1018 </para> 1020 </para>
1019 1021
1020
1021 <para> 1022 <para>
1022 If you are interested in a more detailed example with complete transcripts showing how to 1023 The basic steps you need to follow are:
1023 create a BSP that is based on an existing similar BSP, see the information on the wiki 1024 <orderedlist>
1024 page at <ulink url='https://wiki.yoctoproject.org/wiki/BKM:_starting_a_new_BSP'></ulink>. 1025 <listitem><para>Make sure you have the Yocto Project source tree available.
1026 You should either create a Yocto Project Git repository (recommended), or
1027 you should get the Yocto Project release tarball and extract it.</para></listitem>
1028 <listitem><para>Choose an existing BSP available with the Yocto Project.
1029 Try to map your board features as closely to the features of a BSP that is
1030 already supported and exists in the Yocto Project.
1031 Starting with something as close as possible to your board makes developing
1032 your BSP easier.
1033 You can find all the BSPs that are supported and ship with the Yocto Project
1034 on the Yocto Project's Download page at
1035 <ulink url='http://www.yoctoproject.org/download'></ulink>.</para></listitem>
1036 <listitem><para>Be sure you have the Base BSP.
1037 You need to either have the Yocto Project Git repository set up or download
1038 the tarball of the base BSP.
1039 Either method gives you access to the BSP source files.</para></listitem>
1040 <listitem><para>Make a copy of the existing BSP, thus isolating your new BSP work.
1041 Copying the existing BSP structure gives you a new area in which to work.</para></listitem>
1042 <listitem><para>Make configuration and recipe changes to your new BSP.
1043 Configuration changes involve the files in the BSP's <filename>conf</filename>
1044 directory.
1045 Changes include creating a machine-specific configuration file and editing the
1046 <filename>layer.conf</filename> file.
1047 The configuration changes identify the kernel you will be using.
1048 Recipe changes include removing, modifying, or adding new recipe files that
1049 instruct the build process on what features to include in the image.</para></listitem>
1050 <listitem><para>Prepare for the build.
1051 Before you actually initiate the build you need to set up the build environment
1052 by sourcing the environment initialization script.
1053 After setting up the environment you need to make some build configuration
1054 changes to the <filename>local.conf</filename> and <filename>bblayers.conf</filename>
1055 files.</para></listitem>
1056 <listitem><para>Build the image.
1057 The Yocto Project uses the BitBake tool to create the image.
1058 You need to decide on the type of image you are going to build (e.g. minimal, base,
1059 core, sato, and so forth) and then start the build using the <filename>bitbake</filename>
1060 command.</para></listitem>
1061 </orderedlist>
1025 </para> 1062 </para>
1026
1027 <orderedlist>
1028 <listitem><para>
1029 Identify a machine configuration file that matches your machine.
1030 </para>
1031
1032 <para>
1033 You can start with a machine configuration file in the Yocto Project source tree
1034 such as the <filename>atom-pc.conf</filename> in <filename>meta-yocto/conf/machine</filename>.
1035 Or, you can start with a machine configuration file from a BSP layer
1036 such as <filename>emenlow.conf</filename> in <filename>meta-emenlow/conf/machine</filename>.
1037 </para>
1038
1039 <para>
1040 The main difference between these two BSP machine configuration files is that "emenlow" is
1041 in its own isolated BSP layer, while "atom-pc" is in a more encompassing layer
1042 named <filename>meta-yocto</filename> that is part of the Yocto Project source tree.
1043 The "emenlow" configuration is in its own BSP layer because the target hardware
1044 needs extra machine-specific packages to support graphics and other features.
1045 The "atom-pc" configuration file supports more basic hardware that does not need any
1046 special packages - everything the hardware needs can be specified in the configuration file.
1047 The "atom-pc" machine also supports all of Asus eee901, Acer Aspire One, Toshiba NB305,
1048 and the Intel&reg; Embedded Development Board 1-N450 with no changes.
1049 </para>
1050
1051 <para>
1052 If you want to make minor changes to support a slightly different machine, you can
1053 create a new configuration file for the new machine and add it alongside the
1054 configuration files.
1055 You might consider keeping common configurations for several machines in a separate file
1056 and then including the other configuration files that have more specific configurations.
1057 </para>
1058
1059 <para>
1060 Similarly, you can also use multiple configuration files for different machines even
1061 when the configuration files come from a separate and different layer.
1062 </para>
1063
1064 <para>
1065 As an example consider this:
1066 <orderedlist>
1067 <listitem><para>Copy the "emenlow" BSP layer to a new BSP layer named
1068 <filename>meta-mymachine</filename>.
1069 Now you have two identical BSP layers &dash; but with different names.</para></listitem>
1070 <listitem><para>This example assumes the hardware for your new BSP is very similar to
1071 the hardware used for <filename>meta-emenlow</filename>.
1072 And, you only need to change some machine configurations and inform the Yocto Project build
1073 process of the new layer.
1074 Consequently, you just need to modify some files in the the new layer so that the Yocto Project
1075 build process uses the recipes and configurations in the new layer.
1076 Since you are basing your new layer on a copied existing layer you need to be sure to rename
1077 any directories named "emenlow" to "mymachine".
1078 There is one in the <filename>recipes-bsp</filename> directory and one in the
1079 <filename>recipes-graphics</filename> directory.</para></listitem>.
1080 <listitem><para>In the <filename>recipes-graphics</filename> directory make sure you locate and
1081 change all occurences of "emenlow" to "mymachine".
1082 Several instances exist.</para></listitem>
1083 <listitem><para>Rename the <filename>emenlow.conf</filename> file to <filename>mymachine.conf</filename>
1084 and fix or remove any configurations.
1085 You need to be sure that "mymachine" replaces "emenlow".
1086 Note also that "linux-yocto" is the kernel specified in the configuration file.</para></listitem>
1087 <listitem><para>Make sure the Yocto Project build process knows about the new BSP
1088 layer by adding the pathname to the new layer to the <filename>bblayers.conf</filename> configuration
1089 file located in the Yocto Project build tree at <filename>build/conf/bblayers.conf</filename>.
1090 Adding the layer allows BitBake to find the new layer.
1091
1092 <note>
1093 The above example creates a BSP layer named <filename>meta-mymachine</filename> that is
1094 functionally identical to the BSP layer on which it was based - <filename>meta-emenlow</filename>.
1095 In a real-world scenario you would need to differentiate features and configurations to enable
1096 your "similar" BSP layer to work on your target hardware.
1097 </note></para></listitem>
1098 </orderedlist>
1099 </para></listitem>
1100
1101 <listitem><para>
1102 Create a machine branch for your machine in a the Yocto Project Git repository.
1103 </para>
1104
1105 <para>
1106 For the kernel to compile successfully, you need to create a branch in the
1107 Yocto Project Git repository that is specifically named for your machine.
1108 To create this branch, first create a bare clone of the Yocto Project Git repository.
1109 Then, create a local clone of that bare clone.
1110 Here are the commands:
1111 <literallayout class='monospaced'>
1112 $ git clone &dash;&dash;bare git://git.yoctoproject.org/linux-yocto-2.6.37.git linux-yocto-2.6.37.git
1113 $ git clone linux-yocto-2.6.37.git linux-yocto-2.6.37
1114 </literallayout>
1115 </para>
1116
1117 <para>
1118 Now be sure you are in the local clone and create a branch and push it to the bare clone:
1119 <literallayout class='monospaced'>
1120 $ git checkout -b yocto/standard/mymachine origin/yocto/standard/base
1121 $ git push origin yocto/standard/mymachine:yocto/standard/mymachine
1122 </literallayout>
1123 </para></listitem>
1124
1125 <listitem><para>
1126 In your new layer you need to edit the <filename>linux-yocto_git.bbappend</filename>
1127 file so that the compatible machine is "mymachine".
1128 It is also convenient to point to a cloned Yocto Project Git repository that is local
1129 to your system for development purposes.
1130 Thus, change the <filename>linux-yocto_git.bbappend</filename> file in your
1131 <filename>meta-mymachine</filename> layer to the following:
1132 </para>
1133
1134 <para>
1135 <literallayout class='monospaced'>
1136 FILESEXTRAPATHS := "${THISDIR}/${PN}"
1137 COMPATIBLE_MACHINE_mymachine = "mymachine"
1138
1139 # It is often nice to have a clone of the kernel repository, to
1140 # allow patches to be staged, branches created, and so forth. Modify
1141 # KSRC to point to your bare clone as appropriate.
1142
1143 KSRC ?= $MYWORK/linux-yocto-2.6.37.git
1144
1145 # KMACHINE is the branch to be built, or alternatively
1146 # KBRANCH can be directly set.
1147 # KBRANCH is set to KMACHINE in the main linux-yocto_git.bb
1148 # KBRANCH ?= "${LINUX_KERNEL_TYPE}/${KMACHINE}"
1149
1150 KMACHINE_mymachine = "yocto/standard/mymachine"
1151
1152 SRC_URI = "git://${KSRC};nocheckout=1;branch=${KBRANCH},meta;name=machine,meta"
1153 </literallayout>
1154 </para>
1155
1156 <para>
1157 After updating the <filename>linux-yocto_git.bbappend</filename> file,
1158 edit the <filename>build/conf/local.conf</filename> found
1159 in the Yocto Project build tree so that it selects your machine:
1160 <literallayout class='monospaced'>
1161 #
1162 MACHINE ?= "mymachine"
1163 #
1164 </literallayout>
1165 </para>
1166
1167 <para>
1168 You should now be able to build and boot an image with the new kernel:
1169 <literallayout class='monospaced'>
1170 $ bitbake -k core-image-sato-live
1171 </literallayout>
1172 </para></listitem>
1173
1174 <listitem><para>
1175 Modify the kernel configuration for your machine.
1176 </para>
1177
1178 <para>
1179 At this point you will build a kernel with the default configuration file, which is probably
1180 not what you want.
1181 If you just want to set some kernel configuration options, you can do that by
1182 putting them in a file.
1183 For example, inserting the following into some <filename>.cfg</filename> file:
1184 <literallayout class='monospaced'>
1185 CONFIG_NETDEV_1000=y
1186 CONFIG_E1000E=y
1187 </literallayout>
1188 </para>
1189
1190 <para>
1191 And, another <filename>.cfg</filename> file would contain:
1192 <literallayout class='monospaced'>
1193 CONFIG_LOG_BUF_SHIFT=18
1194 </literallayout>
1195 </para>
1196
1197 <para>
1198 These configuration fragments could then be picked up and
1199 applied to the kernel .config by appending them to the kernel SRC_URI:
1200 <literallayout class='monospaced'>
1201 SRC_URI_append_mymachine = " file://some.cfg \
1202 file://other.cfg \
1203 "
1204 </literallayout>
1205 </para>
1206
1207 <para>
1208 You could also add these directly to the git repository <filename>meta</filename>
1209 branch as well.
1210 However, the former method is a simple starting point.
1211 </para></listitem>
1212
1213 <listitem><para>
1214 If you're also adding patches to the kernel, you can do the same thing.
1215 Put your patches in the SRC_URI as well (plus <filename>.cfg</filename> for their kernel
1216 configuration options if needed).
1217 </para>
1218
1219 <para>
1220 Practically speaking, to generate the patches, you'd go to the source in the build tree:
1221 <literallayout class='monospaced'>
1222 build/tmp/work/mymachine-poky-linux/linux-yocto-2.6.37+Git0+d1cd5c80ee97e81e130be8c3de3965b770f320d6_0+
12230431115c9d720fee5bb105f6a7411efb4f851d26-r13/linux
1224 </literallayout>
1225 </para>
1226
1227 <para>
1228 Then, modify the code there, using quilt to save the changes, and recompile until
1229 it works:
1230 <literallayout class='monospaced'>
1231 $ bitbake -c compile -f linux-yocto
1232 </literallayout>
1233 </para></listitem>
1234
1235 <listitem><para>
1236 Once you have the final patch from quilt, copy it to the
1237 SRC_URI location.
1238 The patch is applied the next time you do a clean build.
1239 Of course, since you have a branch for the BSP in Git, it would be better to put it there instead.
1240 For example, in this case, commit the patch to the "yocto/standard/mymachine" branch, and during the
1241 next build it is applied from there.
1242 </para></listitem>
1243 </orderedlist>
1244 </section> 1063 </section>
1245 1064
1246 1065
1066<!--
1247 <section id='bsp-creating-bsp-without-a-local-kernel-repo'> 1067 <section id='bsp-creating-bsp-without-a-local-kernel-repo'>
1248 <title>Creating a BSP Based on an Existing Similar BSP Without a Local Kernel Repository</title> 1068 <title>Creating a BSP Based on an Existing Similar BSP Without a Local Kernel Repository</title>
1249 1069
@@ -1276,7 +1096,8 @@ That's it. Configure and build.
1276 </section> 1096 </section>
1277 1097
1278 1098
1279<!-- <section id='bsp-creating-a-new-bsp'> 1099
1100 <section id='bsp-creating-a-new-bsp'>
1280 <title>BSP: Creating a New BSP</title> 1101 <title>BSP: Creating a New BSP</title>
1281<para> 1102<para>
1282Although it is obvious that the structure of a new BSP uses the migrated 1103Although it is obvious that the structure of a new BSP uses the migrated
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2025-11-17 10:43:16 +0000