Blame - yocto-poky/documentation/kernel-dev/kernel-dev-common.xml - openbmc/openbmc

The path <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-THISDIR'><filename>THISDIR</filename></ulink><filename>}/${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>

103

expands to "linux-yocto" in the current directory for this

104

example.

105

If you add any new files that modify the kernel recipe and you

106

have extended <filename>FILESPATH</filename> as

107

described above, you must place the files in your layer in the

108

following area:

109

110

<replaceable>your-layer</replaceable>/recipes-kernel/linux/linux-yocto/

111

</literallayout>

112

<note>If you are working on a new machine Board Support Package

113

(BSP), be sure to refer to the

114

<ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.

</note>

</para>

</section>

<title>Applying Patches</title>

121

122

<para>

123

If you have a single patch or a small series of patches

124

that you want to apply to the Linux kernel source, you

125

can do so just as you would with any other recipe.

126

You first copy the patches to the path added to

127

<ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>

128

in your <filename>.bbappend</filename> file as described in

129

the previous section, and then reference them in

statements.

</para>

<para>

For example, you can apply a three-patch series by adding the

136

following lines to your linux-yocto

137

<filename>.bbappend</filename> file in your layer:

138

139

SRC_URI += "file://0001-first-change.patch"

140

SRC_URI += "file://0002-second-change.patch"

141

SRC_URI += "file://0003-third-change.patch"

142

</literallayout>

143

The next time you run BitBake to build the Linux kernel,

144

BitBake detects the change in the recipe and fetches and

145

applies the patches before building the kernel.

</para>

<para>

For a detailed example showing how to patch the kernel, see the

150

"<ulink url='&YOCTO_DOCS_DEV_URL;#patching-the-kernel'>Patching the Kernel</ulink>"

151

section in the Yocto Project Development Manual.

</para>

</section>

<title>Changing the Configuration</title>

157

158

<para>

159

You can make wholesale or incremental changes to the final

160

<filename>.config</filename> file used for the eventual

161

Linux kernel configuration by including a

162

<filename>defconfig</filename> file and by specifying

163

configuration fragments in the

164

165

to be applied to that file.

</para>

<para>

If you have a complete, working Linux kernel

170

<filename>.config</filename>

171

file you want to use for the configuration, as before, copy

172

that file to the appropriate <filename>${PN}</filename>

173

directory in your layer's

174

<filename>recipes-kernel/linux</filename> directory,

175

and rename the copied file to "defconfig".

176

Then, add the following lines to the linux-yocto

177

<filename>.bbappend</filename> file in your layer:

178

179

FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"

180

SRC_URI += "file://defconfig"

181

</literallayout>

182

The <filename>SRC_URI</filename> tells the build system how to

183

search for the file, while the

184

<ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>

185

extends the

186

<ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>

187

variable (search directories) to include the

188

<filename>${PN}</filename> directory you created to hold the

189

configuration changes.

</para>

<note>

The build system applies the configurations from the

194

<filename>defconfig</filename> file before applying any

195

subsequent configuration fragments.

196

The final kernel configuration is a combination of the

197

configurations in the <filename>defconfig</filename> file and

198

any configuration fragments you provide.

199

You need to realize that if you have any configuration

200

fragments, the build system applies these on top of and

201

after applying the existing <filename>defconfig</filename>

file configurations.

</note>

<para>

Generally speaking, the preferred approach is to determine the

207

incremental change you want to make and add that as a

208

configuration fragment.

209

For example, if you want to add support for a basic serial

210

console, create a file named <filename>8250.cfg</filename> in

211

the <filename>${PN}</filename> directory with the following

212

content (without indentation):

213

214

CONFIG_SERIAL_8250=y

215

CONFIG_SERIAL_8250_CONSOLE=y

216

CONFIG_SERIAL_8250_PCI=y

217

CONFIG_SERIAL_8250_NR_UARTS=4

218

CONFIG_SERIAL_8250_RUNTIME_UARTS=4

219

CONFIG_SERIAL_CORE=y

220

CONFIG_SERIAL_CORE_CONSOLE=y

221

</literallayout>

222

Next, include this configuration fragment and extend the

223

<filename>FILESPATH</filename> variable in your

224

<filename>.bbappend</filename> file:

225

226

FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"

227

SRC_URI += "file://8250.cfg"

228

</literallayout>

229

The next time you run BitBake to build the Linux kernel, BitBake

230

detects the change in the recipe and fetches and applies the

231

new configuration before building the kernel.

</para>

<para>

For a detailed example showing how to configure the kernel,

236

see the

237

"<ulink url='&YOCTO_DOCS_DEV_URL;#configuring-the-kernel'>Configuring the Kernel</ulink>"

238

section in the Yocto Project Development Manual.

</para>

</section>

<title>Using an "In-Tree"  <filename>defconfig</filename> File</title>

244

245

<para>

246

It might be desirable to have kernel configuration fragment

247

support through a <filename>defconfig</filename> file that

248

is pulled from the kernel source tree for the configured

249

machine.

250

By default, the OpenEmbedded build system looks for

251

<filename>defconfig</filename> files in the layer used for

252

Metadata, which is "out-of-tree", and then configures them

253

using the following:

254

255

SRC_URI += "file://defconfig"

256

</literallayout>

257

If you do not want to maintain copies of

258

<filename>defconfig</filename> files in your layer but would

259

rather allow users to use the default configuration from the

260

kernel tree and still be able to add configuration fragments

261

to the

262

263

through, for example, append files, you can direct the

264

OpenEmbedded build system to use a

265

<filename>defconfig</filename> file that is "in-tree".

</para>

<para>

To specify an "in-tree" <filename>defconfig</filename> file,

270

edit the recipe that builds your kernel so that it has the

271

following command form:

272

273

KBUILD_DEFCONFIG_<ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'>KMACHINE</ulink> ?= <replaceable>defconfig_file</replaceable>

274

</literallayout>

275

You need to append the variable with

276

<filename>KMACHINE</filename> and then supply the path to

277

your "in-tree" <filename>defconfig</filename> file.

</para>

<para>

Aside from modifying your kernel recipe and providing your own

282

<filename>defconfig</filename> file, you need to be sure no

283

files or statements set <filename>SRC_URI</filename> to use a

284

<filename>defconfig</filename> other than your "in-tree"

285

file (e.g. a kernel's <filename>linux-</filename><replaceable>machine</replaceable><filename>.inc</filename>

286

file).

287

In other words, if the build system detects a statement

288

that identifies an "out-of-tree"

289

<filename>defconfig</filename> file, that statement

290

will override your

291

<filename>KBUILD_DEFCONFIG</filename> variable.

</para>

<para>

See the

<ulink url='&YOCTO_DOCS_REF_URL;#var-KBUILD_DEFCONFIG'><filename>KBUILD_DEFCONFIG</filename></ulink>

297

variable description for more information.

</para>

</section>

</section>

<title>Using an Iterative Development Process</title>

304

305

<para>

306

If you do not have existing patches or configuration files,

307

you can iteratively generate them from within the BitBake build

308

environment as described within this section.

309

During an iterative workflow, running a previously completed BitBake

310

task causes BitBake to invalidate the tasks that follow the

311

completed task in the build sequence.

312

Invalidated tasks rebuild the next time you run the build using

BitBake.

</para>

<para>

As you read this section, be sure to substitute the name

318

of your Linux kernel recipe for the term

"linux-yocto".

</para>

<title>"-dirty" String</title>

<!--

<para>

<emphasis>AR - Darren Hart:</emphasis> This section

328

originated from the old Yocto Project Kernel Architecture

329

and Use Manual.

330

It was decided we need to put it in this section here.

331

Darren needs to figure out where we want it and what part

332

of it we want (all, revision???)

</para>

-->

<para>

If kernel images are being built with "-dirty" on the

338

end of the version string, this simply means that

339

modifications in the source directory have not been committed.

$ git status

</literallayout>

</para>

<para>

You can use the above Git command to report modified,

347

removed, or added files.

348

You should commit those changes to the tree regardless of

349

whether they will be saved, exported, or used.

350

Once you commit the changes, you need to rebuild the kernel.

</para>

<para>

To force a pickup and commit of all such pending changes,

enter the following:

$ git add .

$ git commit -s -a -m "getting rid of -dirty"

</literallayout>

</para>

<para>

Next, rebuild the kernel.

</para>

</section>

<title>Generating Configuration Files</title>

369

370

<para>

371

You can manipulate the <filename>.config</filename> file

372

used to build a linux-yocto recipe with the

373

<filename>menuconfig</filename> command as follows:

374

375

$ bitbake linux-yocto -c menuconfig

376

</literallayout>

377

This command starts the Linux kernel configuration tool,

378

which allows you to prepare a new

379

<filename>.config</filename> file for the build.

380

When you exit the tool, be sure to save your changes

at the prompt.

</para>

<para>

The resulting <filename>.config</filename> file is

386

located in

387

<filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename> under the

388

<filename>linux-${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink><filename>}-${<ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></ulink>}-build</filename> directory.

389

You can use the entire <filename>.config</filename> file as the

390

<filename>defconfig</filename> file as described in the

391

"<link linkend='changing-the-configuration'>Changing the Configuration</link>" section.

</para>

<para>

A better method is to create a configuration fragment using the

396

differences between two configuration files: one previously

397

created and saved, and one freshly created using the

398

<filename>menuconfig</filename> tool.

</para>

<para>

To create a configuration fragment using this method, follow

403

these steps:

404

405

<listitem><para>Complete a build at least through the kernel

406

configuration task as follows:

407

408

$ bitbake linux-yocto -c kernel_configme -f

409

</literallayout>

410

This step ensures that you will be creating a

411

<filename>.config</filename> file from a known state.

412

Because situations exist where your build state might

413

become unknown, it is best to run the previous

414

command prior to starting up

415

<filename>menuconfig</filename>.

416

</para></listitem>

417

<listitem><para>Run the <filename>menuconfig</filename>

418

command:

419

420

$ bitbake linux-yocto -c menuconfig

421

</literallayout></para></listitem>

422

<listitem><para>Run the <filename>diffconfig</filename>

423

command to prepare a configuration fragment.

424

The resulting file <filename>fragment.cfg</filename>

425

will be placed in the

426

<filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename> directory:

427

428

$ bitbake linux-yocto -c diffconfig

429

</literallayout></para></listitem>

</orderedlist>

</para>

<para>

The <filename>diffconfig</filename> command creates a file that is a

435

list of Linux kernel <filename>CONFIG_</filename> assignments.

436

See the "<link linkend='changing-the-configuration'>Changing the Configuration</link>"

437

section for information on how to use the output as a

438

configuration fragment.

439

<note>

440

You can also use this method to create configuration

441

fragments for a BSP.

442

See the "<link linkend='bsp-descriptions'>BSP Descriptions</link>"

443

section for more information.

</note>

</para>

<para>

The kernel tools also provide configuration validation.

449

You can use these tools to produce warnings for when a

450

requested configuration does not appear in the final

451

<filename>.config</filename> file or when you override a

452

policy configuration in a hardware configuration fragment.

453

Here is an example with some sample output of the command

454

that runs these tools:

455

456

$ bitbake linux-yocto -c kernel_configcheck -f

...

NOTE: validating kernel configuration

461

This BSP sets 3 invalid/obsolete kernel options.

462

These config options are not offered anywhere within this kernel.

463

The full list can be found in your kernel src dir at:

464

meta/cfg/standard/mybsp/invalid.cfg

465

466

This BSP sets 21 kernel options that are possibly non-hardware related.

467

The full list can be found in your kernel src dir at:

468

meta/cfg/standard/mybsp/specified_non_hdw.cfg

469

470

WARNING: There were 2 hardware options requested that do not

471

have a corresponding value present in the final ".config" file.

472

This probably means you are not getting the config you wanted.

473

The full list can be found in your kernel src dir at:

474

meta/cfg/standard/mybsp/mismatch.cfg

</literallayout>

</para>

<para>

The output describes the various problems that you can

480

encounter along with where to find the offending configuration

481

items.

482

You can use the information in the logs to adjust your

483

configuration files and then repeat the

484

<filename>kernel_configme</filename> and

485

<filename>kernel_configcheck</filename> commands until

486

they produce no warnings.

</para>

<para>

For more information on how to use the

491

<filename>menuconfig</filename> tool, see the

492

"<ulink url='&YOCTO_DOCS_DEV_URL;#using-menuconfig'>Using <filename>menuconfig</filename></ulink>"

493

section in the Yocto Project Development Manual.

</para>

</section>

<title>Modifying Source Code</title>

499

500

<para>

501

You can experiment with source code changes and create a

502

simple patch without leaving the BitBake environment.

503

To get started, be sure to complete a build at

504

least through the kernel configuration task:

505

506

$ bitbake linux-yocto -c kernel_configme -f

507

</literallayout>

508

Taking this step ensures you have the sources prepared

509

and the configuration completed.

510

You can find the sources in the

511

<filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}/linux</filename> directory.

</para>

<para>

You can edit the sources as you would any other Linux source

516

tree.

517

However, keep in mind that you will lose changes if you

518

trigger the

519

<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-fetch'><filename>do_fetch</filename></ulink>

520

task for the recipe.

521

You can avoid triggering this task by not using BitBake to

522

run the

523

<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleanall'><filename>cleanall</filename></ulink>,

524

<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-cleansstate'><filename>cleansstate</filename></ulink>,

525

or forced

526

<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-fetch'><filename>fetch</filename></ulink>

527

commands.

528

Also, do not modify the recipe itself while working

529

with temporary changes or BitBake might run the

530

<filename>fetch</filename> command depending on the

531

changes to the recipe.

</para>

<para>

To test your temporary changes, instruct BitBake to run the

536

<filename>compile</filename> again.

537

The <filename>-f</filename> option forces the command to run

538

even though BitBake might think it has already done so:

539

540

$ bitbake linux-yocto -c compile -f

541

</literallayout>

542

If the compile fails, you can update the sources and repeat

543

the <filename>compile</filename>.

544

Once compilation is successful, you can inspect and test

545

the resulting build (i.e. kernel, modules, and so forth) from

546

the following build directory:

547

548

${WORKDIR}/linux-${PACKAGE_ARCH}-${LINUX_KERNEL_TYPE}-build

549

</literallayout>

550

Alternatively, you can run the <filename>deploy</filename>

551

command to place the kernel image in the

552

<filename>tmp/deploy/images</filename> directory:

553

554

$ bitbake linux-yocto -c deploy

555

</literallayout>

556

And, of course, you can perform the remaining installation and

557

packaging steps by issuing:

558

559

$ bitbake linux-yocto

</literallayout>

</para>

<para>

For rapid iterative development, the edit-compile-repeat loop

565

described in this section is preferable to rebuilding the

566

entire recipe because the installation and packaging tasks

567

are very time consuming.

</para>

<para>

Once you are satisfied with your source code modifications,

572

you can make them permanent by generating patches and

573

applying them to the

574

575

statement as described in the

576

"<link linkend='applying-patches'>Applying Patches</link>"

577

section.

578

If you are not familiar with generating patches, refer to the

579

"<ulink url='&YOCTO_DOCS_DEV_URL;#creating-the-patch'>Creating the Patch</ulink>"

580

section in the Yocto Project Development Manual.

</para>

</section>

</section>

<title>Working With Your Own Sources</title>

587

588

<para>

589

If you cannot work with one of the Linux kernel

590

versions supported by existing linux-yocto recipes, you can

591

still make use of the Yocto Project Linux kernel tooling by

592

working with your own sources.

593

When you use your own sources, you will not be able to

594

leverage the existing kernel

595

<ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> and

596

stabilization work of the linux-yocto sources.

597

However, you will be able to manage your own Metadata in the same

598

format as the linux-yocto sources.

599

Maintaining format compatibility facilitates converging with

600

linux-yocto on a future, mutually-supported kernel version.

</para>

<para>

To help you use your own sources, the Yocto Project provides a

605

linux-yocto custom recipe

606

(<filename>linux-yocto-custom.bb</filename>) that uses

607

<filename>kernel.org</filename> sources

608

and the Yocto Project Linux kernel tools for managing

609

kernel Metadata.

610

You can find this recipe in the

611

<filename>poky</filename> Git repository of the

612

Yocto Project <ulink url='&YOCTO_GIT_URL;'>Source Repository</ulink>

613

at:

614

615

poky/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb

</literallayout>

</para>

<para>

Here are some basic steps you can use to work with your own sources:

621

622

<listitem><para>Copy the <filename>linux-yocto-custom.bb</filename>

623

recipe to your layer and give it a meaningful name.

624

The name should include the version of the Linux kernel you

625

are using (e.g.

626

<filename>linux-yocto-myproject_3.19.bb</filename>,

627

where "3.19" is the base version of the Linux kernel

628

with which you would be working).</para></listitem>

629

<listitem><para>In the same directory inside your layer,

630

create a matching directory

631

to store your patches and configuration files (e.g.

632

<filename>linux-yocto-myproject</filename>).

633

</para></listitem>

634

<listitem><para>Make sure you have either a

635

<filename>defconfig</filename> file or configuration

636

fragment files.

637

When you use the <filename>linux-yocto-custom.bb</filename>

638

recipe, you must specify a configuration.

639

If you do not have a <filename>defconfig</filename> file,

640

you can run the following:

$ make defconfig

</literallayout>

After running the command, copy the resulting

645

<filename>.config</filename> to the

646

<filename>files</filename> directory as "defconfig" and

647

then add it to the

648

649

variable in the recipe.</para>

650

<para>Running the <filename>make defconfig</filename>

651

command results in the default configuration for your

652

architecture as defined by your kernel.

653

However, no guarantee exists that this configuration is

654

valid for your use case, or that your board will even boot.

655

This is particularly true for non-x86 architectures.

656

To use non-x86 <filename>defconfig</filename> files, you

657

need to be more specific and find one that matches your

658

board (i.e. for arm, you look in

659

<filename>arch/arm/configs</filename> and use the one that

660

is the best starting point for your board).

661

</para></listitem>

662

<listitem><para>Edit the following variables in your recipe

663

as appropriate for your project:

664

665

<listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>:

666

The <filename>SRC_URI</filename> should specify

667

a Git repository that uses one of the supported Git

668

fetcher protocols (i.e. <filename>file</filename>,

669

<filename>git</filename>, <filename>http</filename>,

670

and so forth).

671

The <filename>SRC_URI</filename> variable should

672

also specify either a <filename>defconfig</filename>

673

file or some configuration fragment files.

674

The skeleton recipe provides an example

675

<filename>SRC_URI</filename> as a syntax reference.

676

</para></listitem>

677

<listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_VERSION'><filename>LINUX_VERSION</filename></ulink>:

678

The Linux kernel version you are using (e.g.

679

"3.19").</para></listitem>

680

<listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_VERSION_EXTENSION'><filename>LINUX_VERSION_EXTENSION</filename></ulink>:

681

The Linux kernel <filename>CONFIG_LOCALVERSION</filename>

682

that is compiled into the resulting kernel and visible

683

through the <filename>uname</filename> command.

684

</para></listitem>

685

<listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>:

686

The commit ID from which you want to build.

687

</para></listitem>

688

<listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>:

689

Treat this variable the same as you would in any other

690

recipe.

691

Increment the variable to indicate to the OpenEmbedded

692

build system that the recipe has changed.

693

</para></listitem>

694

<listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>:

695

The default <filename>PV</filename> assignment is

696

typically adequate.

697

It combines the <filename>LINUX_VERSION</filename>

698

with the Source Control Manager (SCM) revision

699

as derived from the

700

<ulink url='&YOCTO_DOCS_REF_URL;#var-SRCPV'><filename>SRCPV</filename></ulink>

701

variable.

702

The combined results are a string with

703

the following form:

704

705

3.19.11+git1+68a635bf8dfb64b02263c1ac80c948647cc76d5f_1+218bd8d2022b9852c60d32f0d770931e3cf343e2

706

</literallayout>

707

While lengthy, the extra verbosity in <filename>PV</filename>

708

helps ensure you are using the exact

709

sources from which you intend to build.

710

</para></listitem>

711

<listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></ulink>:

712

A list of the machines supported by your new recipe.

713

This variable in the example recipe is set

714

by default to a regular expression that matches

715

only the empty string, "(^$)".

716

This default setting triggers an explicit build

717

failure.

718

You must change it to match a list of the machines

719

that your new recipe supports.

720

For example, to support the <filename>qemux86</filename>

721

and <filename>qemux86-64</filename> machines, use

722

the following form:

723

724

COMPATIBLE_MACHINE = "qemux86|qemux86-64"

725

</literallayout></para></listitem>

726

</itemizedlist></para></listitem>

727

<listitem><para>Provide further customizations to your recipe

728

as needed just as you would customize an existing

729

linux-yocto recipe.

730

See the "<link linkend='modifying-an-existing-recipe'>Modifying

731

an Existing Recipe</link>" section for information.

</para></listitem>

</orderedlist>

</para>

</section>

<title>Working with Out-of-Tree Modules</title>

739

740

<para>

741

This section describes steps to build out-of-tree modules on

742

your target and describes how to incorporate out-of-tree modules

in the build.

</para>

<title>Building Out-of-Tree Modules on the Target</title>

748

749

<para>

750

While the traditional Yocto Project development model would be

751

to include kernel modules as part of the normal build

752

process, you might find it useful to build modules on the

753

target.

754

This could be the case if your target system is capable

755

and powerful enough to handle the necessary compilation.

756

Before deciding to build on your target, however, you should

757

consider the benefits of using a proper cross-development

758

environment from your build host.

</para>

<para>

If you want to be able to build out-of-tree modules on

763

the target, there are some steps you need to take

764

on the target that is running your SDK image.

765

Briefly, the <filename>kernel-dev</filename> package

766

is installed by default on all

767

<filename>*.sdk</filename> images and the

768

<filename>kernel-devsrc</filename> package is installed

769

on many of the <filename>*.sdk</filename> images.

770

However, you need to create some scripts prior to

771

attempting to build the out-of-tree modules on the target

772

that is running that image.

</para>

<para>

Prior to attempting to build the out-of-tree modules,

777

you need to be on the target as root and you need to

778

change to the <filename>/usr/src/kernel</filename> directory.

779

Next, <filename>make</filename> the scripts:

# cd /usr/src/kernel

# make scripts

</literallayout>

Because all SDK image recipes include

785

<filename>dev-pkgs</filename>, the

786

<filename>kernel-dev</filename> packages will be installed

787

as part of the SDK image and the

788

<filename>kernel-devsrc</filename> packages will be installed

789

as part of applicable SDK images.

790

The SDK uses the scripts when building out-of-tree

791

modules.

792

Once you have switched to that directory and created the

793

scripts, you should be able to build your out-of-tree modules

on the target.

</para>

</section>

<title>Incorporating Out-of-Tree Modules</title>

800

801

<para>

802

While it is always preferable to work with sources integrated

803

into the Linux kernel sources, if you need an external kernel

804

module, the <filename>hello-mod.bb</filename> recipe is

805

available as a template from which you can create your

806

own out-of-tree Linux kernel module recipe.

</para>

<para>

This template recipe is located in the

811

<filename>poky</filename> Git repository of the

812

Yocto Project <ulink url='&YOCTO_GIT_URL;'>Source Repository</ulink>

813

at:

814

815

poky/meta-skeleton/recipes-kernel/hello-mod/hello-mod_0.1.bb

</literallayout>

</para>

<para>

To get started, copy this recipe to your layer and give it a

821

meaningful name (e.g. <filename>mymodule_1.0.bb</filename>).

822

In the same directory, create a new directory named

823

<filename>files</filename> where you can store any source files,

824

patches, or other files necessary for building

825

the module that do not come with the sources.

826

Finally, update the recipe as needed for the module.

827

Typically, you will need to set the following variables:

828

829

<listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-DESCRIPTION'><filename>DESCRIPTION</filename></ulink>

830

</para></listitem>

831

<listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE*</filename></ulink>

</para></listitem>

</para></listitem>

</para></listitem>

</itemizedlist>

</para>

<para>

Depending on the build system used by the module sources,

842

you might need to make some adjustments.

843

For example, a typical module <filename>Makefile</filename>

844

looks much like the one provided with the

845

<filename>hello-mod</filename> template:

obj-m := hello.o

SRC := $(shell pwd)

all:

$(MAKE) -C $(KERNEL_SRC) M=$(SRC)

853

854

modules_install:

855

$(MAKE) -C $(KERNEL_SRC) M=$(SRC) modules_install

...

</literallayout>

</para>

<para>

The important point to note here is the

862

<ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_SRC'><filename>KERNEL_SRC</filename></ulink>

863

variable.

864

The

865

<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-module'><filename>module</filename></ulink>

866

class sets this variable and the

867

<ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_PATH'><filename>KERNEL_PATH</filename></ulink>

868

variable to

869

<filename>${<ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></ulink>}</filename>

870

with the necessary Linux kernel build information to build

871

modules.

872

If your module <filename>Makefile</filename> uses a different

873

variable, you might want to override the

874

<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-compile'><filename>do_compile()</filename></ulink>

875

step, or create a patch to

876

the <filename>Makefile</filename> to work with the more typical

877

<filename>KERNEL_SRC</filename> or

878

<filename>KERNEL_PATH</filename> variables.

</para>

<para>

After you have prepared your recipe, you will likely want to

883

include the module in your images.

884

To do this, see the documentation for the following variables in

885

the Yocto Project Reference Manual and set one of them

886

appropriately for your machine configuration file:

887

888

<listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</filename></ulink>

889

</para></listitem>

890

<listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</filename></ulink>

891

</para></listitem>

892

<listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RDEPENDS'><filename>MACHINE_EXTRA_RDEPENDS</filename></ulink>

893

</para></listitem>

894

<listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RRECOMMENDS'><filename>MACHINE_EXTRA_RRECOMMENDS</filename></ulink>

</para></listitem>

</itemizedlist>

</para>

<para>

Modules are often not required for boot and can be excluded from

901

certain build configurations.

902

The following allows for the most flexibility:

903

904

MACHINE_EXTRA_RRECOMMENDS += "kernel-module-mymodule"

905

</literallayout>

906

The value is derived by appending the module filename without

907

the <filename>.ko</filename> extension to the string

"kernel-module-".

</para>

<para>

Because the variable is

913

<ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>

914

and not a

915

<ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>

916

variable, the build will not fail if this module is not

917

available to include in the image.

</para>

</section>

</section>

<title>Inspecting Changes and Commits</title>

925

926

<para>

927

A common question when working with a kernel is:

928

"What changes have been applied to this tree?"

929

Rather than using "grep" across directories to see what has

930

changed, you can use Git to inspect or search the kernel tree.

931

Using Git is an efficient way to see what has changed in the tree.

</para>

<title>What Changed in a Kernel?</title>

936

937

<para>

938

Following are a few examples that show how to use Git

939

commands to examine changes.

940

These examples are by no means the only way to see changes.

941

<note>

942

In the following examples, unless you provide a commit

943

range, <filename>kernel.org</filename> history is blended

944

with Yocto Project kernel changes.

945

You can form ranges by using branch names from the

946

kernel tree as the upper and lower commit markers with

947

the Git commands.

948

You can see the branch names through the web interface

949

to the Yocto Project source repositories at

950

<ulink url='http://git.yoctoproject.org/cgit.cgi'></ulink>.

951

</note>

952

To see a full range of the changes, use the

953

<filename>git whatchanged</filename> command and specify a

954

commit range for the branch

955

(<replaceable>commit</replaceable><filename>..</filename><replaceable>commit</replaceable>).

</para>

<para>

Here is an example that looks at what has changed in the

960

<filename>emenlow</filename> branch of the

961

<filename>linux-yocto-3.19</filename> kernel.

962

The lower commit range is the commit associated with the

963

<filename>standard/base</filename> branch, while

964

the upper commit range is the commit associated with the

965

<filename>standard/emenlow</filename> branch.

966

967

$ git whatchanged origin/standard/base..origin/standard/emenlow

</literallayout>

</para>

<para>

To see short, one line summaries of changes use the

973

<filename>git log</filename> command:

974

975

$ git log --oneline origin/standard/base..origin/standard/emenlow

</literallayout>

</para>

<para>

Use this command to see code differences for the changes:

981

982

$ git diff origin/standard/base..origin/standard/emenlow

</literallayout>

</para>

<para>

Use this command to see the commit log messages and the

988

text differences:

989

990

$ git show origin/standard/base..origin/standard/emenlow

</literallayout>

</para>

<para>

Use this command to create individual patches for

996

each change.

997

Here is an example that that creates patch files for each

998

commit and places them in your <filename>Documents</filename>

999

directory:

1000

1001

$ git format-patch -o $HOME/Documents origin/standard/base..origin/standard/emenlow

</literallayout>

</para>

</section>

<title>Showing a Particular Feature or Branch Change</title>

1008

1009

<para>

1010

Tags in the Yocto Project kernel tree divide changes for

1011

significant features or branches.

1012

The <filename>git show</filename> <replaceable>tag</replaceable>

1013

command shows changes based on a tag.

1014

Here is an example that shows <filename>systemtap</filename>

changes:

$ git show systemtap

</literallayout>

You can use the

<filename>git branch --contains</filename> <replaceable>tag</replaceable>

1021

command to show the branches that contain a particular feature.

1022

This command shows the branches that contain the

1023

<filename>systemtap</filename> feature:

1024

1025

$ git branch --contains systemtap

</literallayout>

</para>

</section>

</section>

</chapter>

<!--

vim: expandtab tw=80 ts=4

1033

-->