summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
Diffstat (limited to 'documentation')
-rw-r--r--documentation/kernel-dev/kernel-dev-intro.xml206
1 files changed, 173 insertions, 33 deletions
diff --git a/documentation/kernel-dev/kernel-dev-intro.xml b/documentation/kernel-dev/kernel-dev-intro.xml
index 56cf6bc7e2..a2644aaa13 100644
--- a/documentation/kernel-dev/kernel-dev-intro.xml
+++ b/documentation/kernel-dev/kernel-dev-intro.xml
@@ -120,52 +120,192 @@
120 <section id='getting-ready-to-develop-using-devtool'> 120 <section id='getting-ready-to-develop-using-devtool'>
121 <title>Getting Ready to Develop using <filename>devtool</filename></title> 121 <title>Getting Ready to Develop using <filename>devtool</filename></title>
122 122
123 <para role='writernotes'> 123 <para>
124 Sections as follows: 124 Follow these steps to prepare to update the kernel image using
125 <filename>devtool</filename>.
126 Completing this procedure leaves you with a clean kernel image
127 and ready to make modifications as described in the
128 "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>"
129 section:
125 <orderedlist> 130 <orderedlist>
126 <listitem><para role='writernotes'> 131 <listitem><para>
127 Source the oe-init-build-env script. 132 <emphasis>Initialize the BitBake Environment:</emphasis>
128 At this point, we assume the build host is set up and 133 Before building an extensible SDK, you need to
129 <filename>poky</filename> repository has been cloned. 134 initialize the BitBake build environment by sourcing a
135 build environment script
136 (i.e. <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>oe-init-build-env</filename></ulink>
137 or
138 <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>):
139 <literallayout class='monospaced'>
140 $ cd ~/poky
141 $ source oe-init-build-env
142 </literallayout>
143 <note>
144 The previous commands assume the
145 <ulink url='&YOCTO_DOCS_REF_URL;#source-repositories'>Source Repositories</ulink>
146 (i.e. <filename>poky</filename>) have been cloned
147 using Git and the local repository is named
148 "poky".
149 </note>
130 </para></listitem> 150 </para></listitem>
131 <listitem><para role='writernotes'> 151 <listitem><para>
132 Be sure your <filename>local.conf</filename> file has 152 <emphasis>Prepare Your <filename>local.conf</filename> File:</emphasis>
133 the correct 153 By default, the
134 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> 154 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
135 variable set for the target hardware on which your 155 variable is set to "qemux86", which is fine if you are
136 kernel image runs. 156 building for the QEMU emulator in 32-bit mode.
137 Also have the 157 However, if you are not, you need to set the
158 <filename>MACHINE</filename> variable appropriately in
159 your <filename>local.conf</filename> file found in the
160 <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
161 (i.e. <filename>~/poky/build</filename> in this example).
162 </para>
163
164 <para>Also, since you are preparing to work on the kernel
165 image, you need to set the
138 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</filename></ulink> 166 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</filename></ulink>
139 variable set equal to "kernel-modules". 167 variable to include kernel modules.</para>
168
169 <para>This example uses the default "qemux86" for the
170 <filename>MACHINE</filename> variable but needs to
171 add the "kernel-modules":
172 <literallayout class='monospaced'>
173 MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-modules"
174 </literallayout>
140 </para></listitem> 175 </para></listitem>
141 <listitem><para role='writernotes'> 176 <listitem><para>
142 Create a layer for later that will contain your patches 177 <emphasis>Create a Layer for Patches:</emphasis>
143 (if any) to the kernel. 178 You need to create a layer to hold patches created
179 for the kernel image.
180 You can use the <filename>yocto-layer</filename> command
181 as follows:
182 <literallayout class='monospaced'>
183 $ cd ~/poky
184 $ yocto-layer create my-kernel -o ../meta-my-kernel
185 Please enter the layer priority you'd like to use for the layer: [default: 6]
186 Would you like to have an example recipe created? (y/n) [default: n]
187 Would you like to have an example bbappend file created? (y/n) [default: n]
188
189 New layer created in ../meta-my-kernel.
190
191 Don't forget to add it to your BBLAYERS (for details see ../meta-my-kernel/README).
192 </literallayout>
193 </para></listitem>
194 <listitem><para>
195 <emphasis>Inform the BitBake Build Environment About Your Layer:</emphasis>
196 As directed when you created your layer, you need to add
197 the layer to the
198 <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink>
199 variable in the <filename>bblayers.conf</filename> file
200 as follows:
201 <literallayout class='monospaced'>
202 $ cd ~/poky/build
203 $ bitbake-layers add-layer ../../meta-my-kernel
204 </literallayout>
144 </para></listitem> 205 </para></listitem>
145 <listitem><para role='writernotes'> 206 <listitem><para>
146 Build the extensible SDK. 207 <emphasis>Build the Extensible SDK:</emphasis>
208 Use BitBake to build the extensible SDK specifically for
209 the Minnowboard:
210 <literallayout class='monospaced'>
211 $ bitbake core-image-minimal -c populate_sdk_ext
212 </literallayout>
213 Once the build finishes, you can find the SDK installer
214 file (i.e. <filename>*.sh</filename> file) in the
215 following directory:
216 <literallayout class='monospaced'>
217 ~/poky/build/tmp/deploy/sdk
218 </literallayout>
219 For this example, the installer file is named
220 <filename>poky-glibc-x86_64-core-image-minimal-i586-toolchain-ext-&DISTRO;.sh</filename>
147 </para></listitem> 221 </para></listitem>
148 <listitem><para role='writernotes'> 222 <listitem><para>
149 Install the extensible SDK. 223 <emphasis>Install the Extensible SDK:</emphasis>
224 Use the following command to install the SDK.
225 For this example, install the SDK in the default
226 <filename>~/poky_sdk</filename> directory:
227 <literallayout class='monospaced'>
228 $ cd ~/poky/build/tmp/deploy/sdk
229 $ ./poky-glibc-x86_64-core-image-minimal-i586-toolchain-ext-&DISTRO;.sh
230 Poky (Yocto Project Reference Distro) Extensible SDK installer version &DISTRO;
231 ============================================================================
232 Enter target directory for SDK (default: ~/poky_sdk):
233 You are about to install the SDK to "/home/scottrif/poky_sdk". Proceed[Y/n]? Y
234 Extracting SDK......................................done
235 Setting it up...
236 Extracting buildtools...
237 Preparing build system...
238 Parsing recipes: 100% |#################################################################| Time: 0:00:52
239 Initializing tasks: 100% |############## ###############################################| Time: 0:00:04
240 Checking sstate mirror object availability: 100% |######################################| Time: 0:00:00
241 Parsing recipes: 100% |#################################################################| Time: 0:00:33
242 Initializing tasks: 100% |##############################################################| Time: 0:00:00
243 done
244 SDK has been successfully set up and is ready to be used.
245 Each time you wish to use the SDK in a new shell session, you need to source the environment setup script e.g.
246 $ . /home/scottrif/poky_sdk/environment-setup-i586-poky-linux
247 </literallayout>
150 </para></listitem> 248 </para></listitem>
151 <listitem><para role='writernotes'> 249 <listitem><para id='setting-up-the-esdk-terminal'>
152 Set up the terminal so that you can work with the 250 <emphasis>Set Up a New Terminal to Work With the Extensible SDK:</emphasis>
153 extensible SDK. 251 You must set up a new terminal to work with the SDK.
154 This terminal is known as the "eSDK Terminal" unlike the 252 You cannot use the same BitBake shell used to build the
155 terminal that is set up to run BitBake, which is known 253 installer.</para>
156 as the "BitBake Terminal". 254
255 <para>After opening a new shell, run the SDK environment
256 setup script as directed by the output from installing
257 the SDK:
258 <literallayout class='monospaced'>
259 $ source ~/poky_sdk/environment-setup-i586-poky-linux
260 "SDK environment now set up; additionally you may now run devtool to perform development tasks.
261 Run devtool --help for further details.
262 </literallayout>
263 <note>
264 If you get a warning about attempting to use the
265 extensible SDK in an environment set up to run
266 BitBake, you did not use a new shell.
267 </note>
157 </para></listitem> 268 </para></listitem>
158 <listitem><para role='writernotes'> 269 <listitem><para>
159 Build the initial image using the extensible SDK. 270 <emphasis>Build the Clean Image:</emphasis>
271 The final step in preparing to work on the kernel is to
272 build an initial image using <filename>devtool</filename>
273 in the new terminal you just set up and initialized for
274 SDK work:
275 <literallayout class='monospaced'>
276 $ devtool build-image
277 Parsing recipes: 100% |##########################################| Time: 0:00:05
278 Parsing of 830 .bb files complete (0 cached, 830 parsed). 1299 targets, 47 skipped, 0 masked, 0 errors.
279 WARNING: No packages to add, building image core-image-minimal unmodified
280 Loading cache: 100% |############################################| Time: 0:00:00
281 Loaded 1299 entries from dependency cache.
282 NOTE: Resolving any missing task queue dependencies
283 Initializing tasks: 100% |#######################################| Time: 0:00:07
284 Checking sstate mirror object availability: 100% |###############| Time: 0:00:00
285 NOTE: Executing SetScene Tasks
286 NOTE: Executing RunQueue Tasks
287 NOTE: Tasks Summary: Attempted 2866 tasks of which 2604 didn't need to be rerun and all succeeded.
288 NOTE: Successfully built core-image-minimal. You can find output files in /home/scottrif/poky_sdk/tmp/deploy/images/qemux86
289 </literallayout>
290 If you were building for actual hardware and not for
291 emulation, you could flash the image to a USB stick
292 on <filename>/dev/sdd</filename> and boot your device.
293 Use a command similar to the following command to flash
294 the image:
295 <literallayout class='monospaced'>
296 $ sudo dd if=tmp/deploy/images/<replaceable>architecture</replaceable>/core-image-minimal-<replaceable>architecture</replaceable>.wic of=/dev/sdd bs=1MB
297 $ sync
298 </literallayout>
160 </para></listitem> 299 </para></listitem>
161 </orderedlist> 300 </orderedlist>
162 </para> 301 </para>
163 302
164 <para role='writernotes'> 303 <para>
165 At this point, the user has enough stuff set up to work on the 304 At this point you have set up to start making modifications to the
166 kernel. 305 kernel by using the extensible SDK.
167 I will put a section in the "Common Tasks" area of this manual 306 For a continued example, see the
168 that finished out how to make a modification to the kernel. 307 "<link linkend='using-devtool-to-patch-the-kernel'>Using <filename>devtool</filename> to Patch the Kernel</link>"
308 section.
169 </para> 309 </para>
170 </section> 310 </section>
171 311