summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml165
1 files changed, 165 insertions, 0 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index d37f94e74a..db6c29fdc3 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -1036,6 +1036,171 @@ so that there are some definite steps on how to do this. I need more detail her
1036 </section> 1036 </section>
1037 </section> 1037 </section>
1038 1038
1039 <section id='configuring-the-kernel'>
1040 <title>Configuring the Kernel</title>
1041
1042 <para>
1043 Configuring the Linux Yocto kernel consists of making sure the <filename>.config</filename>
1044 file has all the right information in it for the image you are building.
1045 You can use the <filename>menuconfig</filename> tool and configuration fragments to
1046 make sure your <filename>.config</filename> file is just how you need it.
1047 This section describes how to use <filename>menuconfig</filename>, create and use
1048 configuration fragments, and how to interatively tweak your <filename>.config</filename>
1049 file to create the leanest kernel configuration file possible.
1050 </para>
1051
1052 <para>
1053 For concepts on kernel configuration, see the
1054 "<ulink url='http://www.yoctoproject.org/docs/latest/kernel-manual/kernel-manual.html#kernel-configuration'>Kernel Configuration</ulink>"
1055 section in the Yocto Project Kernel Architecture and Use Manual.
1056 </para>
1057
1058 <section id='using-menuconfig'>
1059 <title>Using&nbsp;&nbsp;<filename>menuconfig</filename></title>
1060
1061 <para>
1062 The easiest way to define kernel configurations is to set them through the
1063 <filename>menuconfig</filename> tool.
1064 For general information on <filename>menuconfig</filename>, see
1065 <ulink url='http://en.wikipedia.org/wiki/Menuconfig'></ulink>.
1066 </para>
1067
1068 <para>
1069 To use the <filename>menuconfig</filename> tool in the Yocto Project development
1070 environment, you must build the tool using BitBake.
1071 The following commands build and invoke <filename>menuconfig</filename> assuming the
1072 Yocto Project files top-level directory is <filename>~/poky</filename>:
1073 <literallayout class='monospaced'>
1074 $ cd ~/poky
1075 $ source oe-init-build-env
1076 $ bitbake linux-yocto -c menuconfig
1077 </literallayout>
1078 Once <filename>menuconfig</filename> comes up, its standard interface allows you to
1079 examine and configure all the kernel configuration parameters.
1080 Once you have made your changes, simply exit the tool and save your changes to
1081 create an updated version of the <filename>.config</filename> configuration file.
1082 </para>
1083
1084 <para>
1085 For an example that shows how to change the <filename>SMP_CONFIG</filename> parameter
1086 using <filename>menuconfig</filename>, see the
1087 "<link linkend='changing-the-config-smp-configuration-using-menuconfig'>Changing
1088 the <filename>CONFIG_SMP</filename> Configuration Using <filename>menuconfig</filename></link>"
1089 section.
1090 </para>
1091 </section>
1092
1093 <section id='creating-config-fragments'>
1094 <title>Creating Config Fragments</title>
1095
1096 <para>
1097 Configuration fragments are simply kernel options that appear in a file.
1098 Syntactically, the configuration statement is identical to what would appear
1099 in the <filename>.config</filename>.
1100 For example, issuing the following from the shell would create a config fragment
1101 file named <filename>my_smp.cfg</filename> that enables multi-processor support
1102 within the kernel:
1103 <literallayout class='monospaced'>
1104 $ echo "CONFIG_SMP=y" >> my_smp.cfg
1105 </literallayout>
1106 </para>
1107
1108 <para>
1109 Where do you put your configuration files?
1110 You can place these configuration files in the same area to which the
1111 <filename>SRC_URI</filename> points.
1112 The Yocto Project build process will pick up the configuration and add it to the
1113 kernel's configuration.
1114 For example, assume you add the following to your
1115 <filename>linux-yocto_3.0.bbappend</filename> file:
1116 <literallayout class='monospaced'>
1117 file://my_smp.cfg
1118 </literallayout>
1119 You would put the config fragment file <filename>my_smp.cfg</filename> in your
1120 layer right beneath the directory containing the
1121 <filename>linux-yocto_3.0.bbappend</filename> file and the build system
1122 will pick up and apply the fragment.
1123 </para>
1124 </section>
1125
1126 <section id='fine-tuning-the-kernel-configuration-file'>
1127 <title>Fine-tuning the Kernel Configuration File</title>
1128
1129 <para>
1130 You can make sure the <filename>.config</filename> is as lean or efficient as
1131 possible by reading the output of the kernel configuration fragment audit,
1132 noting any issues, making changes to correct the issues, and then repeating.
1133 </para>
1134
1135 <para>
1136 As part of the Linux Yocto kernel build process, the
1137 <filename>kernel_configcheck</filename> task runs.
1138 This task validates the kernel configuration by checking the final
1139 <filename>.config</filename> file against the input files.
1140 During the check, the task produces warning messages for the following
1141 issues:
1142 <itemizedlist>
1143 <listitem><para>Requested options that did not make the final
1144 <filename>.config</filename> file.</para></listitem>
1145 <listitem><para>Configuration items that appear twice in the same
1146 configuration fragment.</para></listitem>
1147 <listitem><para>Configuration items tagged as 'required' were overridden.
1148 </para></listitem>
1149 <listitem><para>A board overrides a non-board specific option.</para></listitem>
1150 <listitem><para>Listed options not valid for the kernel being processed.
1151 In other words, the option does not appear anywhere.</para></listitem>
1152 </itemizedlist>
1153 <note>
1154 The <filename>kernel_configcheck</filename> task can also optionally report
1155 if an option is overridden during processing.
1156 </note>
1157 </para>
1158
1159 <para>
1160 For each output warning, a message points to the file
1161 that contains a list of the options and a pointer to the config
1162 fragment that defines them.
1163 Collectively, the files are the key to streamlining the configiguration.
1164 </para>
1165
1166 <para>
1167 To streamline the configuration, do the following:
1168 <orderedlist>
1169 <listitem><para>Start with a full configuration that you know
1170 works - it builds and boots successfully.
1171 This configuration file will be your baseline.</para></listitem>
1172 <listitem><para>Separately run the <filename>configme</filename> and
1173 <filename>kernel_configcheck</filename> tasks.</para></listitem>
1174 <listitem><para>Take the resulting list of files from the
1175 <filename>kernel_configcheck</filename> task warnings and do the following:
1176 <itemizedlist>
1177 <listitem><para>Drop values that are redefined in the fragment but do not
1178 change the final <filename>.config</filename> file.</para></listitem>
1179 <listitem><para>Analyze and potentially drop values from the
1180 <filename>.config</filename> file that override required
1181 configurations.</para></listitem>
1182 <listitem><para>Analyze and potentially remove non-board specific options.
1183 </para></listitem>
1184 <listitem><para>Remove repeated and invalid options.</para></listitem>
1185 </itemizedlist></para></listitem>
1186 <listitem><para>After you have worked through the output of the kernel configuration
1187 audit, you can re-run the <filename>configme</filename>
1188 and <filename>kernel_configcheck</filename> tasks to see the results of your
1189 changes.
1190 If you have more issues, you can deal with them as described in the
1191 previous step.</para></listitem>
1192 </orderedlist>
1193 </para>
1194
1195 <para>
1196 Iteratively working through steps two through four eventually yields
1197 a minimal, streamlined configuration file.
1198 Once you have the best <filename>.config</filename>, you can build the Linux
1199 Yocto kernel.
1200 </para>
1201 </section>
1202 </section>
1203
1039 <section id="usingpoky-configuring-DISTRO_PN_ALIAS"> 1204 <section id="usingpoky-configuring-DISTRO_PN_ALIAS">
1040 <title>Handling a Package Name Alias</title> 1205 <title>Handling a Package Name Alias</title>
1041 <para> 1206 <para>