diff options
Diffstat (limited to 'documentation/kernel-manual')
-rw-r--r-- | documentation/kernel-manual/kernel-how-to.xml | 277 |
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® 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 ‐ 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 ‐‐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+ | ||
1223 | 0431115c9d720fee5bb105f6a7411efb4f851d26-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> |
1282 | Although it is obvious that the structure of a new BSP uses the migrated | 1103 | Although it is obvious that the structure of a new BSP uses the migrated |