summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
Diffstat (limited to 'documentation')
-rw-r--r--documentation/bsp-guide/bsp.xml638
-rw-r--r--documentation/kernel-dev/kernel-dev-advanced.xml390
-rw-r--r--documentation/kernel-dev/kernel-dev-common.xml149
3 files changed, 635 insertions, 542 deletions
diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml
index 4d0ace0484..cb9940c77a 100644
--- a/documentation/bsp-guide/bsp.xml
+++ b/documentation/bsp-guide/bsp.xml
@@ -352,135 +352,139 @@
352 </para> 352 </para>
353 353
354 <section id="bsp-filelayout-license"> 354 <section id="bsp-filelayout-license">
355 <title>License Files</title> 355 <title>License Files</title>
356 356
357 <para> 357 <para>
358 You can find these files in the BSP Layer at: 358 You can find these files in the BSP Layer at:
359 <literallayout class='monospaced'> 359 <literallayout class='monospaced'>
360 meta-<replaceable>bsp_name</replaceable>/<replaceable>bsp_license_file</replaceable> 360 meta-<replaceable>bsp_name</replaceable>/<replaceable>bsp_license_file</replaceable>
361 </literallayout> 361 </literallayout>
362 </para> 362 </para>
363 363
364 <para> 364 <para>
365 These optional files satisfy licensing requirements for the BSP. 365 These optional files satisfy licensing requirements for the BSP.
366 The type or types of files here can vary depending on the licensing requirements. 366 The type or types of files here can vary depending on the licensing requirements.
367 For example, in the Raspberry Pi BSP all licensing requirements are handled with the 367 For example, in the Raspberry Pi BSP all licensing requirements are handled with the
368 <filename>COPYING.MIT</filename> file. 368 <filename>COPYING.MIT</filename> file.
369 </para> 369 </para>
370 370
371 <para> 371 <para>
372 Licensing files can be MIT, BSD, GPLv*, and so forth. 372 Licensing files can be MIT, BSD, GPLv*, and so forth.
373 These files are recommended for the BSP but are optional and totally up to the BSP developer. 373 These files are recommended for the BSP but are optional and totally up to the BSP developer.
374 </para> 374 </para>
375 </section> 375 </section>
376 376
377 <section id="bsp-filelayout-readme"> 377 <section id="bsp-filelayout-readme">
378 <title>README File</title> 378 <title>README File</title>
379 <para> 379
380 You can find this file in the BSP Layer at: 380 <para>
381 <literallayout class='monospaced'> 381 You can find this file in the BSP Layer at:
382 <literallayout class='monospaced'>
382 meta-<replaceable>bsp_name</replaceable>/README 383 meta-<replaceable>bsp_name</replaceable>/README
383 </literallayout> 384 </literallayout>
384 </para> 385 </para>
385 386
386 <para> 387 <para>
387 This file provides information on how to boot the live images that are optionally 388 This file provides information on how to boot the live images that are optionally
388 included in the <filename>binary/</filename> directory. 389 included in the <filename>binary/</filename> directory.
389 The <filename>README</filename> file also provides special information needed for 390 The <filename>README</filename> file also provides special information needed for
390 building the image. 391 building the image.
391 </para> 392 </para>
392 393
393 <para> 394 <para>
394 At a minimum, the <filename>README</filename> file must 395 At a minimum, the <filename>README</filename> file must
395 contain a list of dependencies, such as the names of 396 contain a list of dependencies, such as the names of
396 any other layers on which the BSP depends and the name of 397 any other layers on which the BSP depends and the name of
397 the BSP maintainer with his or her contact information. 398 the BSP maintainer with his or her contact information.
398 </para> 399 </para>
399 </section> 400 </section>
400 401
401 <section id="bsp-filelayout-readme-sources"> 402 <section id="bsp-filelayout-readme-sources">
402 <title>README.sources File</title> 403 <title>README.sources File</title>
403 <para> 404
404 You can find this file in the BSP Layer at: 405 <para>
405 <literallayout class='monospaced'> 406 You can find this file in the BSP Layer at:
407 <literallayout class='monospaced'>
406 meta-<replaceable>bsp_name</replaceable>/README.sources 408 meta-<replaceable>bsp_name</replaceable>/README.sources
407 </literallayout> 409 </literallayout>
408 </para> 410 </para>
409 411
410 <para> 412 <para>
411 This file provides information on where to locate the BSP 413 This file provides information on where to locate the BSP
412 source files used to build the images (if any) that reside in 414 source files used to build the images (if any) that reside in
413 <filename>meta-<replaceable>bsp_name</replaceable>/binary</filename>. 415 <filename>meta-<replaceable>bsp_name</replaceable>/binary</filename>.
414 Images in the <filename>binary</filename> would be images 416 Images in the <filename>binary</filename> would be images
415 released with the BSP. 417 released with the BSP.
416 The information in the <filename>README.sources</filename> 418 The information in the <filename>README.sources</filename>
417 file also helps you find the 419 file also helps you find the
418 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> 420 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
419 used to generate the images that ship with the BSP. 421 used to generate the images that ship with the BSP.
420 <note> 422 <note>
421 If the BSP's <filename>binary</filename> directory is 423 If the BSP's <filename>binary</filename> directory is
422 missing or the directory has no images, an existing 424 missing or the directory has no images, an existing
423 <filename>README.sources</filename> file is 425 <filename>README.sources</filename> file is
424 meaningless. 426 meaningless.
425 </note> 427 </note>
426 </para> 428 </para>
427 </section> 429 </section>
428 430
429 <section id="bsp-filelayout-binary"> 431 <section id="bsp-filelayout-binary">
430 <title>Pre-built User Binaries</title> 432 <title>Pre-built User Binaries</title>
431 <para> 433
432 You can find these files in the BSP Layer at: 434 <para>
433 <literallayout class='monospaced'> 435 You can find these files in the BSP Layer at:
436 <literallayout class='monospaced'>
434 meta-<replaceable>bsp_name</replaceable>/binary/<replaceable>bootable_images</replaceable> 437 meta-<replaceable>bsp_name</replaceable>/binary/<replaceable>bootable_images</replaceable>
435 </literallayout> 438 </literallayout>
436 </para> 439 </para>
437 440
438 <para> 441 <para>
439 This optional area contains useful pre-built kernels and 442 This optional area contains useful pre-built kernels and
440 user-space filesystem images released with the BSP that are 443 user-space filesystem images released with the BSP that are
441 appropriate to the target system. 444 appropriate to the target system.
442 This directory typically contains graphical (e.g. Sato) and 445 This directory typically contains graphical (e.g. Sato) and
443 minimal live images when the BSP tarball has been created and 446 minimal live images when the BSP tarball has been created and
444 made available in the 447 made available in the
445 <ulink url='&YOCTO_HOME_URL;'>Yocto Project</ulink> website. 448 <ulink url='&YOCTO_HOME_URL;'>Yocto Project</ulink> website.
446 You can use these kernels and images to get a system running 449 You can use these kernels and images to get a system running
447 and quickly get started on development tasks. 450 and quickly get started on development tasks.
448 </para> 451 </para>
449 452
450 <para> 453 <para>
451 The exact types of binaries present are highly 454 The exact types of binaries present are highly
452 hardware-dependent. 455 hardware-dependent.
453 The <filename>README</filename> file should be present in the 456 The <filename>README</filename> file should be present in the
454 BSP Layer and it will explain how to use the images with the 457 BSP Layer and it will explain how to use the images with the
455 target hardware. 458 target hardware.
456 Additionally, the <filename>README.sources</filename> file 459 Additionally, the <filename>README.sources</filename> file
457 should be present to locate the sources used to build the 460 should be present to locate the sources used to build the
458 images and provide information on the Metadata. 461 images and provide information on the Metadata.
459 </para> 462 </para>
460 </section> 463 </section>
461 464
462 <section id='bsp-filelayout-layer'> 465 <section id='bsp-filelayout-layer'>
463 <title>Layer Configuration File</title> 466 <title>Layer Configuration File</title>
464 <para> 467
465 You can find this file in the BSP Layer at: 468 <para>
466 <literallayout class='monospaced'> 469 You can find this file in the BSP Layer at:
470 <literallayout class='monospaced'>
467 meta-<replaceable>bsp_name</replaceable>/conf/layer.conf 471 meta-<replaceable>bsp_name</replaceable>/conf/layer.conf
468 </literallayout> 472 </literallayout>
469 </para> 473 </para>
470 474
471 <para> 475 <para>
472 The <filename>conf/layer.conf</filename> file identifies the file structure as a 476 The <filename>conf/layer.conf</filename> file identifies the file structure as a
473 layer, identifies the 477 layer, identifies the
474 contents of the layer, and contains information about how the build 478 contents of the layer, and contains information about how the build
475 system should use it. 479 system should use it.
476 Generally, a standard boilerplate file such as the following works. 480 Generally, a standard boilerplate file such as the following works.
477 In the following example, you would replace "<replaceable>bsp</replaceable>" and 481 In the following example, you would replace "<replaceable>bsp</replaceable>" and
478 "<replaceable>_bsp</replaceable>" with the actual name 482 "<replaceable>_bsp</replaceable>" with the actual name
479 of the BSP (i.e. <replaceable>bsp_name</replaceable> from the example template). 483 of the BSP (i.e. <replaceable>bsp_name</replaceable> from the example template).
480 </para> 484 </para>
481 485
482 <para> 486 <para>
483 <literallayout class='monospaced'> 487 <literallayout class='monospaced'>
484 # We have a conf and classes directory, add to BBPATH 488 # We have a conf and classes directory, add to BBPATH
485 BBPATH .= ":${LAYERDIR}" 489 BBPATH .= ":${LAYERDIR}"
486 490
@@ -493,13 +497,13 @@
493 BBFILE_PRIORITY_<replaceable>bsp</replaceable> = "6" 497 BBFILE_PRIORITY_<replaceable>bsp</replaceable> = "6"
494 498
495 LAYERDEPENDS_<replaceable>bsp</replaceable> = "intel" 499 LAYERDEPENDS_<replaceable>bsp</replaceable> = "intel"
496 </literallayout> 500 </literallayout>
497 </para> 501 </para>
498 502
499 <para> 503 <para>
500 To illustrate the string substitutions, here are the corresponding statements 504 To illustrate the string substitutions, here are the corresponding statements
501 from the Raspberry Pi <filename>conf/layer.conf</filename> file: 505 from the Raspberry Pi <filename>conf/layer.conf</filename> file:
502 <literallayout class='monospaced'> 506 <literallayout class='monospaced'>
503 # We have a conf and classes directory, append to BBPATH 507 # We have a conf and classes directory, append to BBPATH
504 BBPATH .= ":${LAYERDIR}" 508 BBPATH .= ":${LAYERDIR}"
505 509
@@ -513,316 +517,196 @@
513 517
514 # Additional license directories. 518 # Additional license directories.
515 LICENSE_PATH += "${LAYERDIR}/files/custom-licenses" 519 LICENSE_PATH += "${LAYERDIR}/files/custom-licenses"
516 </literallayout> 520 </literallayout>
517 </para> 521 </para>
518 522
519 <para> 523 <para>
520 This file simply makes 524 This file simply makes
521 <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink> 525 <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink>
522 aware of the recipes and configuration directories. 526 aware of the recipes and configuration directories.
523 The file must exist so that the OpenEmbedded build system can recognize the BSP. 527 The file must exist so that the OpenEmbedded build system can recognize the BSP.
524 </para> 528 </para>
525 </section> 529 </section>
526 530
527 <section id="bsp-filelayout-machine"> 531 <section id="bsp-filelayout-machine">
528 <title>Hardware Configuration Options</title> 532 <title>Hardware Configuration Options</title>
529 <para> 533
530 You can find these files in the BSP Layer at: 534 <para>
531 <literallayout class='monospaced'> 535 You can find these files in the BSP Layer at:
536 <literallayout class='monospaced'>
532 meta-<replaceable>bsp_name</replaceable>/conf/machine/*.conf 537 meta-<replaceable>bsp_name</replaceable>/conf/machine/*.conf
533 </literallayout> 538 </literallayout>
534 </para> 539 </para>
535 540
536 <para> 541 <para>
537 The machine files bind together all the information contained elsewhere 542 The machine files bind together all the information contained elsewhere
538 in the BSP into a format that the build system can understand. 543 in the BSP into a format that the build system can understand.
539 If the BSP supports multiple machines, multiple machine configuration files 544 If the BSP supports multiple machines, multiple machine configuration files
540 can be present. 545 can be present.
541 These filenames correspond to the values to which users have set the 546 These filenames correspond to the values to which users have set the
542 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> variable. 547 <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> variable.
543 </para> 548 </para>
544 549
545 <para> 550 <para>
546 These files define things such as the kernel package to use 551 These files define things such as the kernel package to use
547 (<ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></ulink> 552 (<ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></ulink>
548 of virtual/kernel), the hardware drivers to 553 of virtual/kernel), the hardware drivers to
549 include in different types of images, any special software components 554 include in different types of images, any special software components
550 that are needed, any bootloader information, and also any special image 555 that are needed, any bootloader information, and also any special image
551 format requirements. 556 format requirements.
552 </para> 557 </para>
553 558
554 <para> 559 <para>
555 Each BSP Layer requires at least one machine file. 560 Each BSP Layer requires at least one machine file.
556 However, you can supply more than one file. 561 However, you can supply more than one file.
557 </para> 562 </para>
558 563
559 <para> 564 <para>
560 This configuration file could also include a hardware "tuning" 565 This configuration file could also include a hardware "tuning"
561 file that is commonly used to define the package architecture 566 file that is commonly used to define the package architecture
562 and specify optimization flags, which are carefully chosen 567 and specify optimization flags, which are carefully chosen
563 to give best performance on a given processor. 568 to give best performance on a given processor.
564 </para> 569 </para>
565 570
566 <para> 571 <para>
567 Tuning files are found in the <filename>meta/conf/machine/include</filename> 572 Tuning files are found in the <filename>meta/conf/machine/include</filename>
568 directory within the 573 directory within the
569 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. 574 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
570 For example, the <filename>ia32-base.inc</filename> file resides in the 575 For example, the <filename>ia32-base.inc</filename> file resides in the
571 <filename>meta/conf/machine/include</filename> directory. 576 <filename>meta/conf/machine/include</filename> directory.
572 </para> 577 </para>
573 578
574 <para> 579 <para>
575 To use an include file, you simply include them in the 580 To use an include file, you simply include them in the
576 machine configuration file. 581 machine configuration file.
577 For example, the Raspberry Pi BSP 582 For example, the Raspberry Pi BSP
578 <filename>raspberrypi3.conf</filename> contains the 583 <filename>raspberrypi3.conf</filename> contains the
579 following statement: 584 following statement:
580 <literallayout class='monospaced'> 585 <literallayout class='monospaced'>
581 include conf/machine/raspberrypi2.conf 586 include conf/machine/raspberrypi2.conf
582 </literallayout> 587 </literallayout>
583 </para> 588 </para>
584 </section> 589 </section>
585 590
586 <section id='bsp-filelayout-misc-recipes'> 591 <section id='bsp-filelayout-misc-recipes'>
587 <title>Miscellaneous BSP-Specific Recipe Files</title> 592 <title>Miscellaneous BSP-Specific Recipe Files</title>
588 <para> 593
589 You can find these files in the BSP Layer at: 594 <para>
590 <literallayout class='monospaced'> 595 You can find these files in the BSP Layer at:
596 <literallayout class='monospaced'>
591 meta-<replaceable>bsp_name</replaceable>/recipes-bsp/* 597 meta-<replaceable>bsp_name</replaceable>/recipes-bsp/*
592 </literallayout> 598 </literallayout>
593 </para> 599 </para>
594 600
595 <para> 601 <para>
596 This optional directory contains miscellaneous recipe files for 602 This optional directory contains miscellaneous recipe files for
597 the BSP. 603 the BSP.
598 Most notably would be the formfactor files. 604 Most notably would be the formfactor files.
599 For example, in the Raspberry Pi BSP there is the 605 For example, in the Raspberry Pi BSP there is the
600 <filename>formfactor_0.0.bbappend</filename> file, which is an 606 <filename>formfactor_0.0.bbappend</filename> file, which is an
601 append file used to augment the recipe that starts the build. 607 append file used to augment the recipe that starts the build.
602 Furthermore, there are machine-specific settings used during 608 Furthermore, there are machine-specific settings used during
603 the build that are defined by the 609 the build that are defined by the
604 <filename>machconfig</filename> file further down in the 610 <filename>machconfig</filename> file further down in the
605 directory. 611 directory.
606 Here is the <filename>machconfig</filename> 612 Here is the <filename>machconfig</filename>
607 file for the Raspberry Pi BSP: 613 file for the Raspberry Pi BSP:
608 <literallayout class='monospaced'> 614 <literallayout class='monospaced'>
609 HAVE_TOUCHSCREEN=0 615 HAVE_TOUCHSCREEN=0
610 HAVE_KEYBOARD=1 616 HAVE_KEYBOARD=1
611 617
612 DISPLAY_CAN_ROTATE=0 618 DISPLAY_CAN_ROTATE=0
613 DISPLAY_ORIENTATION=0 619 DISPLAY_ORIENTATION=0
614 DISPLAY_DPI=133 620 DISPLAY_DPI=133
615 </literallayout> 621 </literallayout>
616 </para> 622 </para>
617 623
618 <note><para> 624 <note><para>
619 If a BSP does not have a formfactor entry, defaults are established according to 625 If a BSP does not have a formfactor entry, defaults are established according to
620 the formfactor configuration file that is installed by the main 626 the formfactor configuration file that is installed by the main
621 formfactor recipe 627 formfactor recipe
622 <filename>meta/recipes-bsp/formfactor/formfactor_0.0.bb</filename>, 628 <filename>meta/recipes-bsp/formfactor/formfactor_0.0.bb</filename>,
623 which is found in the 629 which is found in the
624 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>. 630 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
625 </para></note> 631 </para></note>
626 </section> 632 </section>
627 633
628 <section id='bsp-filelayout-recipes-graphics'> 634 <section id='bsp-filelayout-recipes-graphics'>
629 <title>Display Support Files</title> 635 <title>Display Support Files</title>
630 <para> 636
631 You can find these files in the BSP Layer at: 637 <para>
632 <literallayout class='monospaced'> 638 You can find these files in the BSP Layer at:
639 <literallayout class='monospaced'>
633 meta-<replaceable>bsp_name</replaceable>/recipes-graphics/* 640 meta-<replaceable>bsp_name</replaceable>/recipes-graphics/*
634 </literallayout> 641 </literallayout>
635 </para> 642 </para>
636 643
637 <para> 644 <para>
638 This optional directory contains recipes for the BSP if it has 645 This optional directory contains recipes for the BSP if it has
639 special requirements for graphics support. 646 special requirements for graphics support.
640 All files that are needed for the BSP to support a display are 647 All files that are needed for the BSP to support a display are
641 kept here. 648 kept here.
642 </para> 649 </para>
643 </section> 650 </section>
644 651
645 <section id='bsp-filelayout-kernel'> 652 <section id='bsp-filelayout-kernel'>
646 <title>Linux Kernel Configuration</title> 653 <title>Linux Kernel Configuration</title>
647 <para>
648 You can find these files in the BSP Layer at:
649 <literallayout class='monospaced'>
650 meta-<replaceable>bsp_name</replaceable>/recipes-kernel/linux/linux-yocto*.bbappend
651 </literallayout>
652 </para>
653
654 <para>
655 These files append your specific changes to the main kernel recipe you are using.
656 </para>
657 <para>
658 For your BSP, you typically want to use an existing Yocto Project kernel recipe found in the
659 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
660 at <filename>meta/recipes-kernel/linux</filename>.
661 You can append your specific changes to the kernel recipe by using a
662 similarly named append file, which is located in the BSP Layer (e.g.
663 the <filename>meta-<replaceable>bsp_name</replaceable>/recipes-kernel/linux</filename> directory).
664 </para>
665 <para>
666 Suppose you are using the <filename>linux-yocto_4.4.bb</filename> recipe to build
667 the kernel.
668 In other words, you have selected the kernel in your
669 <replaceable>bsp_name</replaceable><filename>.conf</filename> file by adding these types
670 of statements:
671 <literallayout class='monospaced'>
672 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
673 PREFERRED_VERSION_linux-yocto ?= "4.4%"
674 </literallayout>
675 <note>
676 When the preferred provider is assumed by default, the
677 <filename>PREFERRED_PROVIDER</filename> statement does not appear in the
678 <replaceable>bsp_name</replaceable><filename>.conf</filename> file.
679 </note>
680 You would use the <filename>linux-yocto_4.4.bbappend</filename>
681 file to append specific BSP settings to the kernel, thus
682 configuring the kernel for your particular BSP.
683 </para>
684
685 <para>
686 As an example, consider the following append file
687 used by the BSPs in <filename>meta-yocto-bsp</filename>:
688 <literallayout class='monospaced'>
689 meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.4.bbappend
690 </literallayout>
691 The following listing shows the file.
692 Be aware that the actual commit ID strings in this
693 example listing might be different than the actual strings
694 in the file from the <filename>meta-yocto-bsp</filename>
695 layer upstream.
696 <literallayout class='monospaced'>
697 KBRANCH_genericx86 = "standard/base"
698 KBRANCH_genericx86-64 = "standard/base"
699
700 KMACHINE_genericx86 ?= "common-pc"
701 KMACHINE_genericx86-64 ?= "common-pc-64"
702 KBRANCH_edgerouter = "standard/edgerouter"
703 KBRANCH_beaglebone = "standard/beaglebone"
704 KBRANCH_mpc8315e-rdb = "standard/fsl-mpc8315e-rdb"
705
706 SRCREV_machine_genericx86 ?= "ff4c4ef15b51f45b9106d71bf1f62fe7c02e63c2"
707 SRCREV_machine_genericx86-64 ?= "ff4c4ef15b51f45b9106d71bf1f62fe7c02e63c2"
708 SRCREV_machine_edgerouter ?= "ff4c4ef15b51f45b9106d71bf1f62fe7c02e63c2"
709 SRCREV_machine_beaglebone ?= "ff4c4ef15b51f45b9106d71bf1f62fe7c02e63c2"
710 SRCREV_machine_mpc8315e-rdb ?= "df00877ef9387b38b9601c82db57de2a1b23ce53"
711
712 COMPATIBLE_MACHINE_genericx86 = "genericx86"
713 COMPATIBLE_MACHINE_genericx86-64 = "genericx86-64"
714 COMPATIBLE_MACHINE_edgerouter = "edgerouter"
715 COMPATIBLE_MACHINE_beaglebone = "beaglebone"
716 COMPATIBLE_MACHINE_mpc8315e-rdb = "mpc8315e-rdb"
717
718 LINUX_VERSION_genericx86 = "4.4.3"
719 LINUX_VERSION_genericx86-64 = "4.4.3"
720 </literallayout>
721 This append file contains statements used to support
722 several BSPs that ship with the Yocto Project.
723 The file defines machines using the
724 <ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></ulink>
725 variable and uses the
726 <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>
727 variable to ensure the machine name used by the OpenEmbedded
728 build system maps to the machine name used by the Linux Yocto
729 kernel.
730 The file also uses the optional
731 <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink>
732 variable to ensure the build process uses the
733 appropriate kernel branch.
734 </para>
735
736 <para>
737 Although this particular example does not use it, the
738 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink>
739 variable could be used to enable features specific to
740 the kernel.
741 The append file points to specific commits in the
742 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
743 Git repository and the <filename>meta</filename> Git repository
744 branches to identify the exact kernel needed to build the
745 BSP.
746 </para>
747
748 <para>
749 One thing missing in this particular BSP, which you will
750 typically need when developing a BSP, is the kernel configuration
751 file (<filename>.config</filename>) for your BSP.
752 When developing a BSP, you probably have a kernel configuration
753 file or a set of kernel configuration files that, when taken
754 together, define the kernel configuration for your BSP.
755 You can accomplish this definition by putting the configurations
756 in a file or a set of files inside a directory located at the
757 same level as your kernel's append file and having the same
758 name as the kernel's main recipe file.
759 With all these conditions met, simply reference those files in the
760 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
761 statement in the append file.
762 </para>
763 654
764 <para> 655 <para>
765 For example, suppose you had some configuration options 656 You can find these files in the BSP Layer at:
766 in a file called <filename>network_configs.cfg</filename>. 657 <literallayout class='monospaced'>
767 You can place that file inside a directory named 658 meta-<replaceable>bsp_name</replaceable>/recipes-kernel/linux/linux-yocto*.bbappend
768 <filename>linux-yocto</filename> and then add 659 </literallayout>
769 a <filename>SRC_URI</filename> statement such as the 660 </para>
770 following to the append file.
771 When the OpenEmbedded build system builds the kernel, the
772 configuration options are picked up and applied.
773 <literallayout class='monospaced'>
774 SRC_URI += "file://network_configs.cfg"
775 </literallayout>
776 </para>
777 661
778 <para> 662 <para>
779 To group related configurations into multiple files, you 663 These files append machine-specific changes to the main
780 perform a similar procedure. 664 kernel recipe you are using.
781 Here is an example that groups separate configurations 665 </para>
782 specifically for Ethernet and graphics into their own
783 files and adds the configurations by using a
784 <filename>SRC_URI</filename> statement like the following
785 in your append file:
786 <literallayout class='monospaced'>
787 SRC_URI += "file://myconfig.cfg \
788 file://eth.cfg \
789 file://gfx.cfg"
790 </literallayout>
791 </para>
792 666
793 <para> 667 <para>
794 Another variable you can use in your kernel recipe append 668 For your BSP, you typically want to use an existing Yocto
795 file is the 669 Project kernel recipe found in the
796 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink> 670 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
797 variable. 671 at <filename>meta/recipes-kernel/linux</filename>.
798 When you use this statement, you are extending the locations 672 You can append machine-specific changes to the kernel recipe
799 used by the OpenEmbedded system to look for files and 673 by using a similarly named append file, which is located in
800 patches as the recipe is processed. 674 the BSP Layer for your target device (e.g. the
801 </para> 675 <filename>meta-<replaceable>bsp_name</replaceable>/recipes-kernel/linux</filename> directory).
676 </para>
802 677
803 <note>
804 <para> 678 <para>
805 Other methods exist to accomplish grouping and defining configuration options. 679 Suppose you are using the <filename>linux-yocto_4.4.bb</filename>
806 For example, if you are working with a local clone of the kernel repository, 680 recipe to build the kernel.
807 you could checkout the kernel's <filename>meta</filename> branch, make your changes, 681 In other words, you have selected the kernel in your
808 and then push the changes to the local bare clone of the kernel. 682 <replaceable>bsp_name</replaceable><filename>.conf</filename>
809 The result is that you directly add configuration options to the 683 file by adding
810 <filename>meta</filename> branch for your BSP. 684 <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></ulink>
811 The configuration options will likely end up in that location anyway if the BSP gets 685 and
812 added to the Yocto Project. 686 <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_VERSION'><filename>PREFERRED_VERSION</filename></ulink>
687 statements as follows:
688 <literallayout class='monospaced'>
689 PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
690 PREFERRED_VERSION_linux-yocto ?= "4.4%"
691 </literallayout>
692 <note>
693 When the preferred provider is assumed by default, the
694 <filename>PREFERRED_PROVIDER</filename>
695 statement does not appear in the
696 <replaceable>bsp_name</replaceable><filename>.conf</filename> file.
697 </note>
698 You would use the <filename>linux-yocto_4.4.bbappend</filename>
699 file to append specific BSP settings to the kernel, thus
700 configuring the kernel for your particular BSP.
813 </para> 701 </para>
814 702
815 <para> 703 <para>
816 In general, however, the Yocto Project maintainers take care of moving the 704 You can find more information on what your append file
817 <filename>SRC_URI</filename>-specified 705 should contain in the
818 configuration options to the kernel's <filename>meta</filename> branch. 706 "<ulink url='&YOCTO_DOCS_KERNEL_URL;#creating-the-append-file'>Creating the Append File</ulink>"
819 Not only is it easier for BSP developers to not have to worry about putting those 707 section in the Yocto Project Linux Kernel Development
820 configurations in the branch, but having the maintainers do it allows them to apply 708 Manual.
821 'global' knowledge about the kinds of common configuration options multiple BSPs in
822 the tree are typically using.
823 This allows for promotion of common configurations into common features.
824 </para> 709 </para>
825 </note>
826 </section> 710 </section>
827 </section> 711 </section>
828 712
diff --git a/documentation/kernel-dev/kernel-dev-advanced.xml b/documentation/kernel-dev/kernel-dev-advanced.xml
index 1c1b6366db..434c01fafb 100644
--- a/documentation/kernel-dev/kernel-dev-advanced.xml
+++ b/documentation/kernel-dev/kernel-dev-advanced.xml
@@ -524,170 +524,219 @@
524 <title>BSP Descriptions</title> 524 <title>BSP Descriptions</title>
525 525
526 <para> 526 <para>
527 BSP descriptions combine kernel types with hardware-specific 527 BSP descriptions (i.e. <filename>*.scc</filename> files)
528 features. 528 combine kernel types with hardware-specific features.
529 The hardware-specific portion is typically defined 529 The hardware-specific Metadata is typically defined
530 independently, and then aggregated with each supported kernel 530 independently in the BSP layer, and then aggregated with each
531 type. 531 supported kernel type.
532 Consider this simple BSP description that supports the
533 <replaceable>mybsp</replaceable> machine:
534 <literallayout class='monospaced'>
535 <replaceable>mybsp</replaceable>.scc:
536 define KMACHINE <replaceable>mybsp</replaceable>
537 define KTYPE standard
538 define KARCH i386
539
540 kconf <replaceable>mybsp</replaceable>.cfg
541 </literallayout>
542 Every BSP description should define the
543 <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>,
544 <ulink url='&YOCTO_DOCS_REF_URL;#var-KTYPE'><filename>KTYPE</filename></ulink>,
545 and <ulink url='&YOCTO_DOCS_REF_URL;#var-KARCH'><filename>KARCH</filename></ulink>
546 variables.
547 These variables allow the OpenEmbedded build system to identify
548 the description as meeting the criteria set by the recipe being
549 built.
550 This simple example supports the "mybsp" machine for the "standard"
551 kernel and the "i386" architecture.
552 </para>
553
554 <para>
555 Be aware that a hard link between the
556 <filename>KTYPE</filename> variable and a kernel type
557 description file does not exist.
558 Thus, if you do not have kernel types defined in your kernel
559 Metadata, you only need to ensure that the kernel recipe's
560 <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></ulink>
561 variable and the <filename>KTYPE</filename> variable in the
562 BSP description file match.
563 <note> 532 <note>
564 Future versions of the tooling make the specification of 533 For BSPs supported by the Yocto Project, the BSP description
565 <filename>KTYPE</filename> in the BSP optional. 534 files are located in the <filename>bsp</filename> directory
535 of the <filename>yocto-kernel-cache</filename> repository
536 organized under the "Yocto Linux Kernel" heading in the
537 <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi'>Yocto Project Source Repositories</ulink>.
566 </note> 538 </note>
567 </para> 539 </para>
568 540
569 <para> 541 <para>
570 If you did want to separate your kernel policy from your 542 This section provides a BSP description structural overview along
571 hardware configuration, you could do so by specifying a kernel 543 with aggregation concepts as well as a detailed example using
572 type, such as "standard" and including that description file 544 a BSP supported by the Yocto Project (i.e. Minnow Board).
573 in the BSP description file.
574 See the "<link linkend='kernel-types'>Kernel Types</link>" section
575 for more information.
576 </para> 545 </para>
577 546
578 <para> 547 <section id='bsp-description-file-overview'>
579 You might also have multiple hardware configurations that you 548 <title>Overview</title>
580 aggregate into a single hardware description file that you
581 could include in the BSP description file, rather than referencing
582 a single <filename>.cfg</filename> file.
583 Consider the following:
584 <literallayout class='monospaced'>
585 <replaceable>mybsp</replaceable>.scc:
586 define KMACHINE mybsp
587 define KTYPE standard
588 define KARCH i386
589
590 include standard.scc
591 include <replaceable>mybsp</replaceable>-hw.scc
592 </literallayout>
593 </para>
594 549
595 <para> 550 <para>
596 In the above example, <filename>standard.scc</filename> 551 For simplicity, consider the following top-level BSP
597 aggregates all the configuration fragments, patches, and 552 description file.
598 features that make up your standard kernel policy whereas 553 Top-level BSP descriptions files employ both a structure
599 <replaceable>mybsp</replaceable><filename>-hw.scc</filename> 554 and naming convention for consistency.
600 aggregates all those necessary 555 The naming convention for the file is as follows:
601 to support the hardware available on the 556 <literallayout class='monospaced'>
602 <replaceable>mybsp</replaceable> machine. 557 <replaceable>bsp_name</replaceable>-<replaceable>kernel_type</replaceable>.scc
603 For information on how to break a complete 558 </literallayout>
604 <filename>.config</filename> file into the various 559 Here are some example top-level BSP filenames for the
605 configuration fragments, see the 560 Minnow Board BSP, which is supported by the Yocto Project:
606 "<link linkend='generating-configuration-files'>Generating Configuration Files</link>" 561 <literallayout class='monospaced'>
607 section. 562 minnow-standard.scc
608 </para> 563 minnow-preempt-rt.scc
564 minnow-tiny.scc
565 </literallayout>
566 Each file uses the BSP name followed by the kernel type.
567 </para>
609 568
610 <para> 569 <para>
611 Many real-world examples are more complex. 570 is simple BSP description file whose name has the
612 Like any other <filename>.scc</filename> file, BSP 571 form
613 descriptions can aggregate features. 572 <replaceable>mybsp</replaceable><filename>-standard</filename>
614 Consider the Minnow BSP definition from the 573 and supports the <replaceable>mybsp</replaceable> machine using
615 <filename>linux-yocto-3.19</filename> 574 a standard kernel:
616 Git repository: 575 <literallayout class='monospaced'>
617 <literallayout class='monospaced'> 576 define KMACHINE <replaceable>mybsp</replaceable>
618 minnow.scc: 577 define KTYPE standard
619 include cfg/x86.scc 578 define KARCH i386
620 include features/eg20t/eg20t.scc 579
621 include cfg/dmaengine.scc 580 include ktypes/standard
622 include features/power/intel.scc 581
623 include cfg/efi.scc 582 include <replaceable>mybsp</replaceable>.scc
624 include features/usb/ehci-hcd.scc 583
625 include features/usb/ohci-hcd.scc 584 kconf hardware <replaceable>mybsp</replaceable>-<replaceable>extra</replaceable>.cfg
626 include features/usb/usb-gadgets.scc 585 </literallayout>
627 include features/usb/touchscreen-composite.scc 586 Every top-level BSP description file should define the
628 include cfg/timer/hpet.scc 587 <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>,
629 include cfg/timer/rtc.scc 588 <ulink url='&YOCTO_DOCS_REF_URL;#var-KTYPE'><filename>KTYPE</filename></ulink>,
630 include features/leds/leds.scc 589 and <ulink url='&YOCTO_DOCS_REF_URL;#var-KARCH'><filename>KARCH</filename></ulink>
631 include features/spi/spidev.scc 590 variables.
632 include features/i2c/i2cdev.scc 591 These variables allow the OpenEmbedded build system to identify
633 592 the description as meeting the criteria set by the recipe being
634 # Earlyprintk and port debug requires 8250 593 built.
635 kconf hardware cfg/8250.cfg 594 This simple example supports the "mybsp" machine for the "standard"
636 595 kernel and the "i386" architecture.
637 kconf hardware minnow.cfg 596 </para>
638 kconf hardware minnow-dev.cfg
639 </literallayout>
640 </para>
641 597
642 <para> 598 <para>
643 The <filename>minnow.scc</filename> description file includes 599 Be aware that a hard link between the
644 a hardware configuration fragment 600 <filename>KTYPE</filename> variable and a kernel type description
645 (<filename>minnow.cfg</filename>) specific to the Minnow 601 file does not exist.
646 BSP as well as several more general configuration 602 Thus, if you do not have kernel types defined in your kernel
647 fragments and features enabling hardware found on the 603 Metadata, you only need to ensure that the kernel recipe's
648 machine. 604 <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></ulink>
649 This description file is then included in each of the three 605 variable and the <filename>KTYPE</filename> variable in the
650 "minnow" description files for the supported kernel types 606 BSP description file match.
651 (i.e. "standard", "preempt-rt", and "tiny"). 607 <note>
652 Consider the "minnow" description for the "standard" kernel 608 Future versions of the tooling make the specification of
653 type: 609 <filename>KTYPE</filename> in the BSP optional.
654 <literallayout class='monospaced'> 610 </note>
655 minnow-standard.scc: 611 </para>
656 define KMACHINE minnow
657 define KTYPE standard
658 define KARCH i386
659 612
660 include ktypes/standard 613 <para>
614 To separate your kernel policy from your hardware configuration,
615 you include a kernel type (<filename>ktype</filename>), such as
616 "standard".
617 In the previous example, this is done using the following:
618 <literallayout class='monospaced'>
619 include ktypes/standard
620 </literallayout>
621 In the previous example, <filename>ktypes/standard.scc</filename>
622 aggregates all the configuration fragments, patches, and
623 features that make up your standard kernel policy.
624 See the "<link linkend='kernel-types'>Kernel Types</link>" section
625 for more information.
626 </para>
661 627
662 include minnow.scc 628 <para>
629 To aggregate common configurations and features specific to the
630 kernel for <replaceable>mybsp</replaceable>, use the following:
631 <literallayout class='monospaced'>
632 include <replaceable>mybsp</replaceable>.scc
633 </literallayout>
634 For information on how to break a complete
635 <filename>.config</filename> file into the various
636 configuration fragments, see the
637 "<link linkend='generating-configuration-files'>Generating Configuration Files</link>"
638 section.
639 </para>
663 640
664 # Extra minnow configs above the minimal defined in minnow.scc 641 <para>
665 include cfg/efi-ext.scc 642 Finally, if you have any configurations specific to the
666 include features/media/media-all.scc 643 hardware that are not in a <filename>*.scc</filename> file,
667 include features/sound/snd_hda_intel.scc 644 you can include them as follows:
645 <literallayout class='monospaced'>
646 kconf hardware <replaceable>mybsp</replaceable>-<replaceable>extra</replaceable>.cfg
647 </literallayout>
648 </para>
649 </section>
668 650
669 # The following should really be in standard.scc 651 <section id='bsp-description-file-example-minnow'>
670 # USB live-image support 652 <title>Example</title>
671 include cfg/usb-mass-storage.scc
672 include cfg/boot-live.scc
673 653
674 # Basic profiling 654 <para>
675 include features/latencytop/latencytop.scc 655 Many real-world examples are more complex.
676 include features/profiling/profiling.scc 656 Like any other <filename>.scc</filename> file, BSP
657 descriptions can aggregate features.
658 Consider the Minnow BSP definition from the
659 <filename>linux-yocto-4.4</filename> in the
660 Yocto Project
661 <ulink url='&YOCTO_DOCS_DEV_URL;#source-repositories'>Source Repositories</ulink>
662 (i.e.
663 <filename>yocto-kernel-cache/bsp/minnow</filename>):
664 <literallayout class='monospaced'>
665 minnow.scc:
666 include cfg/x86.scc
667 include features/eg20t/eg20t.scc
668 include cfg/dmaengine.scc
669 include features/power/intel.scc
670 include cfg/efi.scc
671 include features/usb/ehci-hcd.scc
672 include features/usb/ohci-hcd.scc
673 include features/usb/usb-gadgets.scc
674 include features/usb/touchscreen-composite.scc
675 include cfg/timer/hpet.scc
676 include features/leds/leds.scc
677 include features/spi/spidev.scc
678 include features/i2c/i2cdev.scc
679 include features/mei/mei-txe.scc
680
681 # Earlyprintk and port debug requires 8250
682 kconf hardware cfg/8250.cfg
683
684 kconf hardware minnow.cfg
685 kconf hardware minnow-dev.cfg
686 </literallayout>
687 </para>
677 688
678 # Requested drivers that don't have an existing scc 689 <para>
679 kconf hardware minnow-drivers-extra.cfg 690 The <filename>minnow.scc</filename> description file includes
680 </literallayout> 691 a hardware configuration fragment
681 The <filename>include</filename> command midway through the file 692 (<filename>minnow.cfg</filename>) specific to the Minnow
682 includes the <filename>minnow.scc</filename> description that 693 BSP as well as several more general configuration
683 defines all hardware enablements for the BSP that is common to all 694 fragments and features enabling hardware found on the
684 kernel types. 695 machine.
685 Using this command significantly reduces duplication. 696 This <filename>minnow.scc</filename> description file is then
686 </para> 697 included in each of the three
698 "minnow" description files for the supported kernel types
699 (i.e. "standard", "preempt-rt", and "tiny").
700 Consider the "minnow" description for the "standard" kernel
701 type:
702 <literallayout class='monospaced'>
703 minnow-standard.scc:
704 define KMACHINE minnow
705 define KTYPE standard
706 define KARCH i386
707
708 include ktypes/standard
709
710 include minnow.scc
711
712 # Extra minnow configs above the minimal defined in minnow.scc
713 include cfg/efi-ext.scc
714 include features/media/media-all.scc
715 include features/sound/snd_hda_intel.scc
716
717 # The following should really be in standard.scc
718 # USB live-image support
719 include cfg/usb-mass-storage.scc
720 include cfg/boot-live.scc
721
722 # Basic profiling
723 include features/latencytop/latencytop.scc
724 include features/profiling/profiling.scc
725
726 # Requested drivers that don't have an existing scc
727 kconf hardware minnow-drivers-extra.cfg
728 </literallayout>
729 The <filename>include</filename> command midway through the file
730 includes the <filename>minnow.scc</filename> description that
731 defines all enabled hardware for the BSP that is common to
732 all kernel types.
733 Using this command significantly reduces duplication.
734 </para>
687 735
688 <para> 736 <para>
689 Now consider the "minnow" description for the "tiny" kernel type: 737 Now consider the "minnow" description for the "tiny" kernel
690 <literallayout class='monospaced'> 738 type:
739 <literallayout class='monospaced'>
691 minnow-tiny.scc: 740 minnow-tiny.scc:
692 define KMACHINE minnow 741 define KMACHINE minnow
693 define KTYPE tiny 742 define KTYPE tiny
@@ -696,22 +745,24 @@
696 include ktypes/tiny 745 include ktypes/tiny
697 746
698 include minnow.scc 747 include minnow.scc
699 </literallayout> 748 </literallayout>
700 As you might expect, the "tiny" description includes quite a 749 As you might expect, the "tiny" description includes quite a
701 bit less. 750 bit less.
702 In fact, it includes only the minimal policy defined by the 751 In fact, it includes only the minimal policy defined by the
703 "tiny" kernel type and the hardware-specific configuration required 752 "tiny" kernel type and the hardware-specific configuration
704 for booting the machine along with the most basic functionality of 753 required for booting the machine along with the most basic
705 the system as defined in the base "minnow" description file. 754 functionality of the system as defined in the base "minnow"
706 </para> 755 description file.
756 </para>
707 757
708 <para> 758 <para>
709 Notice again the three critical variables: 759 Notice again the three critical variables:
710 <filename>KMACHINE</filename>, <filename>KTYPE</filename>, 760 <filename>KMACHINE</filename>, <filename>KTYPE</filename>,
711 and <filename>KARCH</filename>. 761 and <filename>KARCH</filename>.
712 Of these variables, only the <filename>KTYPE</filename> has changed. 762 Of these variables, only the <filename>KTYPE</filename> has changed.
713 It is now set to "tiny". 763 It is now set to "tiny".
714 </para> 764 </para>
765 </section>
715 </section> 766 </section>
716</section> 767</section>
717 768
@@ -795,6 +846,18 @@
795 value when changing the content of files not explicitly listed 846 value when changing the content of files not explicitly listed
796 in the <filename>SRC_URI</filename>. 847 in the <filename>SRC_URI</filename>.
797 </para> 848 </para>
849
850 <para>
851 If the kernel Metadata is in a layer, you cannot simply list the
852 <filename>*.scc</filename> in the <filename>SRC_URI</filename>
853 statement.
854 You need to use the following form from your kernel append file:
855 <literallayout class='monospaced'>
856 SRC_URI_append_<replaceable>myplatform</replaceable> = " \
857 file://<replaceable>myplatform</replaceable>;type=kmeta;destsuffix=<replaceable>myplatform</replaceable> \
858 "
859 </literallayout>
860 </para>
798 </section> 861 </section>
799 862
800 <section id='metadata-outside-the-recipe-space'> 863 <section id='metadata-outside-the-recipe-space'>
@@ -817,7 +880,8 @@
817 <filename>${KMETA}</filename>, in this context, is simply used to 880 <filename>${KMETA}</filename>, in this context, is simply used to
818 name the directory into which the Git fetcher places the Metadata. 881 name the directory into which the Git fetcher places the Metadata.
819 This behavior is no different than any multi-repository 882 This behavior is no different than any multi-repository
820 <filename>SRC_URI</filename> statement used in a recipe. 883 <filename>SRC_URI</filename> statement used in a recipe (e.g.
884 see the previous section).
821 </para> 885 </para>
822 886
823 <para> 887 <para>
diff --git a/documentation/kernel-dev/kernel-dev-common.xml b/documentation/kernel-dev/kernel-dev-common.xml
index a9aafd3c21..d49aa3ce17 100644
--- a/documentation/kernel-dev/kernel-dev-common.xml
+++ b/documentation/kernel-dev/kernel-dev-common.xml
@@ -84,11 +84,11 @@
84 You also name it accordingly based on the linux-yocto recipe 84 You also name it accordingly based on the linux-yocto recipe
85 you are using. 85 you are using.
86 For example, if you are modifying the 86 For example, if you are modifying the
87 <filename>meta/recipes-kernel/linux/linux-yocto_3.19.bb</filename> 87 <filename>meta/recipes-kernel/linux/linux-yocto_4.4.bb</filename>
88 recipe, the append file will typically be located as follows 88 recipe, the append file will typically be located as follows
89 within your custom layer: 89 within your custom layer:
90 <literallayout class='monospaced'> 90 <literallayout class='monospaced'>
91 <replaceable>your-layer</replaceable>/recipes-kernel/linux/linux-yocto_3.19.bbappend 91 <replaceable>your-layer</replaceable>/recipes-kernel/linux/linux-yocto_4.4.bbappend
92 </literallayout> 92 </literallayout>
93 The append file should initially extend the 93 The append file should initially extend the
94 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink> 94 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
@@ -114,6 +114,151 @@
114 <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>. 114 <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
115 </note> 115 </note>
116 </para> 116 </para>
117
118 <para>
119 As an example, consider the following append file
120 used by the BSPs in <filename>meta-yocto-bsp</filename>:
121 <literallayout class='monospaced'>
122 meta-yocto-bsp/recipes-kernel/linux/linux-yocto_4.4.bbappend
123 </literallayout>
124 The following listing shows the file.
125 Be aware that the actual commit ID strings in this
126 example listing might be different than the actual strings
127 in the file from the <filename>meta-yocto-bsp</filename>
128 layer upstream.
129 <literallayout class='monospaced'>
130 KBRANCH_genericx86 = "standard/base"
131 KBRANCH_genericx86-64 = "standard/base"
132
133 KMACHINE_genericx86 ?= "common-pc"
134 KMACHINE_genericx86-64 ?= "common-pc-64"
135 KBRANCH_edgerouter = "standard/edgerouter"
136 KBRANCH_beaglebone = "standard/beaglebone"
137 KBRANCH_mpc8315e-rdb = "standard/fsl-mpc8315e-rdb"
138
139 SRCREV_machine_genericx86 ?= "ad8b1d659ddd2699ebf7d50ef9de8940b157bfc2"
140 SRCREV_machine_genericx86-64 ?= "ad8b1d659ddd2699ebf7d50ef9de8940b157bfc2"
141 SRCREV_machine_edgerouter ?= "cebe1ad56aebd89e0de29412e19433fb441bf13c"
142 SRCREV_machine_beaglebone ?= "cebe1ad56aebd89e0de29412e19433fb441bf13c"
143 SRCREV_machine_mpc8315e-rdb ?= "06c0dbdcba374ca7f92a53d69292d6bb7bc9b0f3"
144
145 COMPATIBLE_MACHINE_genericx86 = "genericx86"
146 COMPATIBLE_MACHINE_genericx86-64 = "genericx86-64"
147 COMPATIBLE_MACHINE_edgerouter = "edgerouter"
148 COMPATIBLE_MACHINE_beaglebone = "beaglebone"
149 COMPATIBLE_MACHINE_mpc8315e-rdb = "mpc8315e-rdb"
150
151 LINUX_VERSION_genericx86 = "4.4.41"
152 LINUX_VERSION_genericx86-64 = "4.4.41"
153 LINUX_VERSION_edgerouter = "4.4.53"
154 LINUX_VERSION_beaglebone = "4.4.53"
155 LINUX_VERSION_mpc8315e-rdb = "4.4.53"
156 </literallayout>
157 This append file contains statements used to support
158 several BSPs that ship with the Yocto Project.
159 The file defines machines using the
160 <ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></ulink>
161 variable and uses the
162 <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>
163 variable to ensure the machine name used by the OpenEmbedded
164 build system maps to the machine name used by the Linux Yocto
165 kernel.
166 The file also uses the optional
167 <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink>
168 variable to ensure the build process uses the
169 appropriate kernel branch.
170 </para>
171
172 <para>
173 Although this particular example does not use it, the
174 <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink>
175 variable could be used to enable features specific to
176 the kernel.
177 The append file points to specific commits in the
178 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
179 Git repository and the <filename>meta</filename> Git repository
180 branches to identify the exact kernel needed to build the
181 BSP.
182 </para>
183
184 <para>
185 One thing missing in this particular BSP, which you will
186 typically need when developing a BSP, is the kernel configuration
187 file (<filename>.config</filename>) for your BSP.
188 When developing a BSP, you probably have a kernel configuration
189 file or a set of kernel configuration files that, when taken
190 together, define the kernel configuration for your BSP.
191 You can accomplish this definition by putting the configurations
192 in a file or a set of files inside a directory located at the
193 same level as your kernel's append file and having the same
194 name as the kernel's main recipe file.
195 With all these conditions met, simply reference those files in the
196 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
197 statement in the append file.
198 </para>
199
200 <para>
201 For example, suppose you had some configuration options
202 in a file called <filename>network_configs.cfg</filename>.
203 You can place that file inside a directory named
204 <filename>linux-yocto</filename> and then add
205 a <filename>SRC_URI</filename> statement such as the
206 following to the append file.
207 When the OpenEmbedded build system builds the kernel, the
208 configuration options are picked up and applied.
209 <literallayout class='monospaced'>
210 SRC_URI += "file://network_configs.cfg"
211 </literallayout>
212 </para>
213
214 <para>
215 To group related configurations into multiple files, you
216 perform a similar procedure.
217 Here is an example that groups separate configurations
218 specifically for Ethernet and graphics into their own
219 files and adds the configurations by using a
220 <filename>SRC_URI</filename> statement like the following
221 in your append file:
222 <literallayout class='monospaced'>
223 SRC_URI += "file://myconfig.cfg \
224 file://eth.cfg \
225 file://gfx.cfg"
226 </literallayout>
227 </para>
228
229 <para>
230 Another variable you can use in your kernel recipe append
231 file is the
232 <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
233 variable.
234 When you use this statement, you are extending the locations
235 used by the OpenEmbedded system to look for files and
236 patches as the recipe is processed.
237 </para>
238
239 <note>
240 <para>
241 Other methods exist to accomplish grouping and defining configuration options.
242 For example, if you are working with a local clone of the kernel repository,
243 you could checkout the kernel's <filename>meta</filename> branch, make your changes,
244 and then push the changes to the local bare clone of the kernel.
245 The result is that you directly add configuration options to the
246 <filename>meta</filename> branch for your BSP.
247 The configuration options will likely end up in that location anyway if the BSP gets
248 added to the Yocto Project.
249 </para>
250
251 <para>
252 In general, however, the Yocto Project maintainers take care of moving the
253 <filename>SRC_URI</filename>-specified
254 configuration options to the kernel's <filename>meta</filename> branch.
255 Not only is it easier for BSP developers to not have to worry about putting those
256 configurations in the branch, but having the maintainers do it allows them to apply
257 'global' knowledge about the kinds of common configuration options multiple BSPs in
258 the tree are typically using.
259 This allows for promotion of common configurations into common features.
260 </para>
261 </note>
117 </section> 262 </section>
118 263
119 <section id='applying-patches'> 264 <section id='applying-patches'>