Blame - yocto-poky/documentation/kernel-dev/kernel-dev-common.xml - stefanberger/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.

Patrick Williams

f1e5d69

2016-03-30 15:21:19 -0500

[diff] [blame]

392

For more information on the <filename>.config</filename> file,

393

see the

394

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

395

section in the Yocto Project Development Manual.

Patrick Williams

c124f4f

2015-09-15 14:41:29 -0500

[diff] [blame]

</para>

<para>

A better method is to create a configuration fragment using the

400

differences between two configuration files: one previously

401

created and saved, and one freshly created using the

402

<filename>menuconfig</filename> tool.

</para>

<para>

To create a configuration fragment using this method, follow

407

these steps:

408

409

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

410

configuration task as follows:

411

412

$ bitbake linux-yocto -c kernel_configme -f

413

</literallayout>

414

This step ensures that you will be creating a

415

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

416

Because situations exist where your build state might

417

become unknown, it is best to run the previous

418

command prior to starting up

419

<filename>menuconfig</filename>.

420

</para></listitem>

421

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

422

command:

423

424

$ bitbake linux-yocto -c menuconfig

425

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

426

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

427

command to prepare a configuration fragment.

428

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

429

will be placed in the

430

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

431

432

$ bitbake linux-yocto -c diffconfig

433

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

</orderedlist>

</para>

<para>

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

439

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

440

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

441

section for information on how to use the output as a

442

configuration fragment.

443

<note>

444

You can also use this method to create configuration

445

fragments for a BSP.

446

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

447

section for more information.

</note>

</para>

<para>

The kernel tools also provide configuration validation.

453

You can use these tools to produce warnings for when a

454

requested configuration does not appear in the final

455

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

456

policy configuration in a hardware configuration fragment.

457

Here is an example with some sample output of the command

458

that runs these tools:

459

460

$ bitbake linux-yocto -c kernel_configcheck -f

...

NOTE: validating kernel configuration

465

This BSP sets 3 invalid/obsolete kernel options.

466

These config options are not offered anywhere within this kernel.

467

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

468

meta/cfg/standard/mybsp/invalid.cfg

469

470

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

471

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

472

meta/cfg/standard/mybsp/specified_non_hdw.cfg

473

474

WARNING: There were 2 hardware options requested that do not

475

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

476

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

477

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

478

meta/cfg/standard/mybsp/mismatch.cfg

</literallayout>

</para>

<para>

The output describes the various problems that you can

484

encounter along with where to find the offending configuration

485

items.

486

You can use the information in the logs to adjust your

487

configuration files and then repeat the

488

<filename>kernel_configme</filename> and

489

<filename>kernel_configcheck</filename> commands until

490

they produce no warnings.

</para>

<para>

For more information on how to use the

495

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

496

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

497

section in the Yocto Project Development Manual.

</para>

</section>

<title>Modifying Source Code</title>

503

504

<para>

505

You can experiment with source code changes and create a

506

simple patch without leaving the BitBake environment.

507

To get started, be sure to complete a build at

508

least through the kernel configuration task:

509

510

$ bitbake linux-yocto -c kernel_configme -f

511

</literallayout>

512

Taking this step ensures you have the sources prepared

513

and the configuration completed.

514

You can find the sources in the

515

<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

520

tree.

521

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

522

trigger the

523

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

524

task for the recipe.

525

You can avoid triggering this task by not using BitBake to

526

run the

527

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

528

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

529

or forced

530

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

531

commands.

532

Also, do not modify the recipe itself while working

533

with temporary changes or BitBake might run the

534

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

535

changes to the recipe.

</para>

<para>

To test your temporary changes, instruct BitBake to run the

540

<filename>compile</filename> again.

541

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

542

even though BitBake might think it has already done so:

543

544

$ bitbake linux-yocto -c compile -f

545

</literallayout>

546

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

547

the <filename>compile</filename>.

548

Once compilation is successful, you can inspect and test

549

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

550

the following build directory:

551

552

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

553

</literallayout>

554

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

555

command to place the kernel image in the

556

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

557

558

$ bitbake linux-yocto -c deploy

559

</literallayout>

560

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

561

packaging steps by issuing:

562

563

$ bitbake linux-yocto

</literallayout>

</para>

<para>

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

569

described in this section is preferable to rebuilding the

570

entire recipe because the installation and packaging tasks

571

are very time consuming.

</para>

<para>

Once you are satisfied with your source code modifications,

576

you can make them permanent by generating patches and

577

applying them to the

578

579

statement as described in the

580

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

581

section.

582

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

583

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

584

section in the Yocto Project Development Manual.

</para>

</section>

</section>

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

591

592

<para>

593

If you cannot work with one of the Linux kernel

594

versions supported by existing linux-yocto recipes, you can

595

still make use of the Yocto Project Linux kernel tooling by

596

working with your own sources.

597

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

598

leverage the existing kernel

599

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

600

stabilization work of the linux-yocto sources.

601

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

602

format as the linux-yocto sources.

603

Maintaining format compatibility facilitates converging with

604

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

</para>

<para>

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

609

linux-yocto custom recipe

610

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

611

<filename>kernel.org</filename> sources

612

and the Yocto Project Linux kernel tools for managing

613

kernel Metadata.

614

You can find this recipe in the

615

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

616

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

617

at:

618

619

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:

625

626

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

627

recipe to your layer and give it a meaningful name.

628

The name should include the version of the Linux kernel you

629

are using (e.g.

630

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

631

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

632

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

633

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

634

create a matching directory

635

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

636

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

637

</para></listitem>

638

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

639

<filename>defconfig</filename> file or configuration

640

fragment files.

641

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

642

recipe, you must specify a configuration.

643

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

644

you can run the following:

$ make defconfig

</literallayout>

After running the command, copy the resulting

649

<filename>.config</filename> to the

650

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

651

then add it to the

652

653

variable in the recipe.</para>

654

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

655

command results in the default configuration for your

656

architecture as defined by your kernel.

657

However, no guarantee exists that this configuration is

658

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

659

This is particularly true for non-x86 architectures.

660

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

661

need to be more specific and find one that matches your

662

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

663

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

664

is the best starting point for your board).

665

</para></listitem>

666

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

667

as appropriate for your project:

668

669

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

670

The <filename>SRC_URI</filename> should specify

671

a Git repository that uses one of the supported Git

672

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

673

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

674

and so forth).

675

The <filename>SRC_URI</filename> variable should

676

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

677

file or some configuration fragment files.

678

The skeleton recipe provides an example

679

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

680

</para></listitem>

681

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

682

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

683

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

684

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

685

The Linux kernel <filename>CONFIG_LOCALVERSION</filename>

686

that is compiled into the resulting kernel and visible

687

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

688

</para></listitem>

689

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

690

The commit ID from which you want to build.

691

</para></listitem>

692

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

693

Treat this variable the same as you would in any other

694

recipe.

695

Increment the variable to indicate to the OpenEmbedded

696

build system that the recipe has changed.

697

</para></listitem>

698

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

699

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

700

typically adequate.

701

It combines the <filename>LINUX_VERSION</filename>

702

with the Source Control Manager (SCM) revision

703

as derived from the

704

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

705

variable.

706

The combined results are a string with

707

the following form:

708

709

3.19.11+git1+68a635bf8dfb64b02263c1ac80c948647cc76d5f_1+218bd8d2022b9852c60d32f0d770931e3cf343e2

710

</literallayout>

711

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

712

helps ensure you are using the exact

713

sources from which you intend to build.

714

</para></listitem>

715

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

716

A list of the machines supported by your new recipe.

717

This variable in the example recipe is set

718

by default to a regular expression that matches

719

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

720

This default setting triggers an explicit build

721

failure.

722

You must change it to match a list of the machines

723

that your new recipe supports.

724

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

725

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

726

the following form:

727

728

COMPATIBLE_MACHINE = "qemux86|qemux86-64"

729

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

730

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

731

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

732

as needed just as you would customize an existing

733

linux-yocto recipe.

734

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

735

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

</para></listitem>

</orderedlist>

</para>

</section>

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

743

744

<para>

745

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

746

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>

752

753

<para>

754

While the traditional Yocto Project development model would be

755

to include kernel modules as part of the normal build

756

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

757

target.

758

This could be the case if your target system is capable

759

and powerful enough to handle the necessary compilation.

760

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

761

consider the benefits of using a proper cross-development

762

environment from your build host.

</para>

<para>

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

767

the target, there are some steps you need to take

768

on the target that is running your SDK image.

769

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

770

is installed by default on all

771

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

772

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

773

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

774

However, you need to create some scripts prior to

775

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

776

that is running that image.

</para>

<para>

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

781

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

782

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

783

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

# cd /usr/src/kernel

# make scripts

</literallayout>

Because all SDK image recipes include

789

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

790

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

791

as part of the SDK image and the

792

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

793

as part of applicable SDK images.

794

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

795

modules.

796

Once you have switched to that directory and created the

797

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

on the target.

</para>

</section>

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

804

805

<para>

806

While it is always preferable to work with sources integrated

807

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

808

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

809

available as a template from which you can create your

810

own out-of-tree Linux kernel module recipe.

</para>

<para>

This template recipe is located in the

815

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

816

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

817

at:

818

819

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

825

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

826

In the same directory, create a new directory named

827

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

828

patches, or other files necessary for building

829

the module that do not come with the sources.

830

Finally, update the recipe as needed for the module.

831

Typically, you will need to set the following variables:

832

833

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

834

</para></listitem>

835

<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,

846

you might need to make some adjustments.

847

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

848

looks much like the one provided with the

849

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

obj-m := hello.o

SRC := $(shell pwd)

all:

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

857

858

modules_install:

859

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

...

</literallayout>

</para>

<para>

The important point to note here is the

866

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

867

variable.

868

The

869

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

870

class sets this variable and the

871

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

872

variable to

873

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

874

with the necessary Linux kernel build information to build

875

modules.

876

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

877

variable, you might want to override the

878

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

879

step, or create a patch to

880

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

881

<filename>KERNEL_SRC</filename> or

882

<filename>KERNEL_PATH</filename> variables.

</para>

<para>

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

887

include the module in your images.

888

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

889

the Yocto Project Reference Manual and set one of them

890

appropriately for your machine configuration file:

891

892

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

893

</para></listitem>

894

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

895

</para></listitem>

896

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

897

</para></listitem>

898

<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

905

certain build configurations.

906

The following allows for the most flexibility:

907

908

MACHINE_EXTRA_RRECOMMENDS += "kernel-module-mymodule"

909

</literallayout>

910

The value is derived by appending the module filename without

911

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

"kernel-module-".

</para>

<para>

Because the variable is

917

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

918

and not a

919

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

920

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

921

available to include in the image.

</para>

</section>

</section>

<title>Inspecting Changes and Commits</title>

929

930

<para>

931

A common question when working with a kernel is:

932

"What changes have been applied to this tree?"

933

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

934

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

935

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

</para>

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

940

941

<para>

942

Following are a few examples that show how to use Git

943

commands to examine changes.

944

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

945

<note>

946

In the following examples, unless you provide a commit

947

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

948

with Yocto Project kernel changes.

949

You can form ranges by using branch names from the

950

kernel tree as the upper and lower commit markers with

951

the Git commands.

952

You can see the branch names through the web interface

953

to the Yocto Project source repositories at

954

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

955

</note>

956

To see a full range of the changes, use the

957

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

958

commit range for the branch

959

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

</para>

<para>

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

964

<filename>emenlow</filename> branch of the

965

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

966

The lower commit range is the commit associated with the

967

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

968

the upper commit range is the commit associated with the

969

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

970

971

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

</literallayout>

</para>

<para>

To see short, one line summaries of changes use the

977

<filename>git log</filename> command:

978

979

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

</literallayout>

</para>

<para>

Use this command to see code differences for the changes:

985

986

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

</literallayout>

</para>

<para>

Use this command to see the commit log messages and the

992

text differences:

993

994

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

</literallayout>

</para>

<para>

Use this command to create individual patches for

1000

each change.

1001

Here is an example that that creates patch files for each

1002

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

1003

directory:

1004

1005

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

</literallayout>

</para>

</section>

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

1012

1013

<para>

1014

Tags in the Yocto Project kernel tree divide changes for

1015

significant features or branches.

1016

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

1017

command shows changes based on a tag.

1018

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>

1025

command to show the branches that contain a particular feature.

1026

This command shows the branches that contain the

1027

<filename>systemtap</filename> feature:

1028

1029

$ git branch --contains systemtap

</literallayout>

</para>

</section>

</section>

</chapter>

<!--

vim: expandtab tw=80 ts=4

1037

-->