summaryrefslogtreecommitdiffstats
path: root/documentation/bsp-guide/bsp.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/bsp-guide/bsp.xml')
-rw-r--r--documentation/bsp-guide/bsp.xml638
1 files changed, 261 insertions, 377 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