summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--documentation/ref-manual/ref-tasks.xml152
1 files changed, 120 insertions, 32 deletions
diff --git a/documentation/ref-manual/ref-tasks.xml b/documentation/ref-manual/ref-tasks.xml
index e9859c1fa9..a3a41ebcc1 100644
--- a/documentation/ref-manual/ref-tasks.xml
+++ b/documentation/ref-manual/ref-tasks.xml
@@ -853,7 +853,10 @@
853 <title><filename>do_compile_kernelmodules</filename></title> 853 <title><filename>do_compile_kernelmodules</filename></title>
854 854
855 <para> 855 <para>
856 Compiles loadable modules for the Linux kernel. 856 Runs the step that builds the kernel modules (if needed).
857 Building a kernel consists of two steps: 1) the kernel
858 (<filename>vmlinux</filename>) is built, and 2) the modules
859 are built (i.e. <filename>make modules</filename>).
857 </para> 860 </para>
858 </section> 861 </section>
859 862
@@ -861,9 +864,21 @@
861 <title><filename>do_diffconfig</filename></title> 864 <title><filename>do_diffconfig</filename></title>
862 865
863 <para> 866 <para>
864 Compares the old and new config files after running the 867 When invoked by the user, this task creates a file containing the
865 <link linkend='ref-tasks-menuconfig'><filename>do_menuconfig</filename></link> 868 differences between the original config as produced by
866 task for the kernel. 869 <link linkend='ref-tasks-kernel_configme'><filename>do_kernel_configme</filename></link>
870 task and the changes made by the user with other methods
871 (i.e. using
872 (<link linkend='ref-tasks-kernel_menuconfig'><filename>do_kernel_menuconfig</filename></link>).
873 Once the file of differences is created, it can be used to create
874 a config fragment that only contains the differences.
875 You can invoke this task from the command line as follows:
876 <literallayout class='monospaced'>
877 $ bitbake linux-yocto -c diffconfig
878 </literallayout>
879 For more information, see the
880 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#generating-configuration-files'>Generating Configuration Files</ulink>"
881 section in the Yocto Project Linux Kernel Development Manual.
867 </para> 882 </para>
868 </section> 883 </section>
869 884
@@ -871,7 +886,12 @@
871 <title><filename>do_kernel_checkout</filename></title> 886 <title><filename>do_kernel_checkout</filename></title>
872 887
873 <para> 888 <para>
874 Checks out source/meta branches for a linux-yocto style kernel. 889 Converts the newly unpacked kernel source into a form with which
890 the OpenEmbedded build system can work.
891 Because the kernel source can be fetched in several different ways,
892 the <filename>do_kernel_checkout</filename> task makes sure that
893 subsequent tasks are given a clean working tree copy of the kernel
894 with the correct branches checked out.
875 </para> 895 </para>
876 </section> 896 </section>
877 897
@@ -879,7 +899,21 @@
879 <title><filename>do_kernel_configcheck</filename></title> 899 <title><filename>do_kernel_configcheck</filename></title>
880 900
881 <para> 901 <para>
882 Validates the kernel configuration for a linux-yocto style kernel. 902 Validates the configuration produced by the
903 <link linkend='ref-tasks-kernel_menuconfig'><filename>do_kernel_menuconfig</filename></link>
904 task.
905 The <filename>do_kernel_configcheck</filename> task produces
906 warnings when a requested configuration does not appear in the
907 final <filename>.config</filename> file or when you override a
908 policy configuration in a hardware configuration fragment.
909 You can run this task explicitly and view the output by using
910 the following command:
911 <literallayout class='monospaced'>
912 $ bitbake linux-yocto -c kernel_configcheck -f
913 </literallayout>
914 For more information, see the
915 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#generating-configuration-files'>Generating Configuration Files</ulink>"
916 section in the Yocto Project Linux Kernel Development Manual.
883 </para> 917 </para>
884 </section> 918 </section>
885 919
@@ -887,17 +921,41 @@
887 <title><filename>do_kernel_configme</filename></title> 921 <title><filename>do_kernel_configme</filename></title>
888 922
889 <para> 923 <para>
890 Assembles the kernel configuration for a linux-yocto style kernel. 924 After the kernel is patched by the
925 <link linkend='ref-tasks-patch'><filename>do_patch</filename></link>
926 task, the <filename>do_kernel_configme</filename> task assembles
927 and merges all the kernel config fragments into a merged
928 configuration that can then be passed to the kernel configuration
929 phase proper.
930 This is also the time during which user-specified defconfigs
931 are applied if present, and where configuration modes such as
932 <filename>--allnoconfig</filename> are applied.
891 </para> 933 </para>
892 </section> 934 </section>
893 935
894 <section id='ref-tasks-kernel_link_vmlinux'> 936 <section id='ref-tasks-kernel_menuconfig'>
895 <title><filename>do_kernel_link_vmlinux</filename></title> 937 <title><filename>do_kernel_menuconfig</filename></title>
896 938
897 <para> 939 <para>
898 Creates a symbolic link in 940 Invoked by the user to manipulate the
899 <filename>arch/$arch/boot</filename> for vmlinux kernel 941 <filename>.config</filename> file used to build a linux-yocto
900 images. 942 recipe.
943 This task starts the Linux kernel configuration tool, which you
944 then use to modify the kernel configuration.
945 <note>
946 You can also invoke this tool from the command line as
947 follows:
948 <literallayout class='monospaced'>
949 $ bitbake linux-yocto -c menuconfig
950 </literallayout>
951 </note>
952 See the
953 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#generating-configuration-files'>Generating Configuration Files</ulink>"
954 section in the Yocto Project Linux Kernel Development Manual
955 for more information on this configuration tool.
956 You can also reference the
957 "<ulink url='&YOCTO_DOCS_DEV_URL;#using-menuconfig'>Using <filename>menuconfig</filename></ulink>"
958 section in the Yocto Project Development Manual.
901 </para> 959 </para>
902 </section> 960 </section>
903 961
@@ -905,8 +963,16 @@
905 <title><filename>do_kernel_metadata</filename></title> 963 <title><filename>do_kernel_metadata</filename></title>
906 964
907 <para> 965 <para>
908 Collects kernel metadata for a 966 Collects all the features required for a given kernel build,
909 <filename>linux-yocto</filename> style kernel. 967 whether the features come from
968 <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
969 or from Git repositories.
970 After collection, the <filename>do_kernel_metadata</filename> task
971 processes the features into a series of config fragments and
972 patches, which can then be applied by subsequent tasks such as
973 <link linkend='ref-tasks-patch'><filename>do_patch</filename></link>
974 and
975 <link linkend='ref-tasks-kernel_configme'><filename>do_kernel_configme</filename></link>.
910 </para> 976 </para>
911 </section> 977 </section>
912 978
@@ -925,7 +991,17 @@
925 <title><filename>do_savedefconfig</filename></title> 991 <title><filename>do_savedefconfig</filename></title>
926 992
927 <para> 993 <para>
928 Creates a minimal Linux kernel configuration file. 994 When invoked by the user, creates a defconfig file that can be
995 used instead of the default defconfig.
996 The saved defconfig contains the differences between the default
997 defconfig and the changes made by the user using other methods
998 (i.e. the
999 <link linkend='ref-tasks-kernel_menuconfig'><filename>do_kernel_menuconfig</filename></link>
1000 task.
1001 You can invoke the task using the following command:
1002 <literallayout class='monospaced'>
1003 $ bitbake linux-yocto -c savedefconfig
1004 </literallayout>
929 </para> 1005 </para>
930 </section> 1006 </section>
931 1007
@@ -933,7 +1009,14 @@
933 <title><filename>do_shared_workdir</filename></title> 1009 <title><filename>do_shared_workdir</filename></title>
934 1010
935 <para> 1011 <para>
936 Creates the shared working directory for the kernel. 1012 After the kernel has been compiled but before the kernel modules
1013 have been compiled, this task copies files required for module
1014 builds and which are generated from the kernel build into the
1015 shared work directory.
1016 With these copies successfully copied, the
1017 <link linkend='ref-tasks-compile_kernelmodules'><filename>do_compile_kernelmodules</filename></link>
1018 task can successfully build the kernel modules in the next step
1019 of the build.
937 </para> 1020 </para>
938 </section> 1021 </section>
939 1022
@@ -941,9 +1024,12 @@
941 <title><filename>do_sizecheck</filename></title> 1024 <title><filename>do_sizecheck</filename></title>
942 1025
943 <para> 1026 <para>
944 Checks the size of the kernel image against 1027 After the kernel has been built, this task checks the size of the
945 <link linkend='var-KERNEL_IMAGE_MAXSIZE'><filename>KERNEL_IMAGE_MAXSIZE</filename></link> 1028 stripped kernel image against
946 when set. 1029 <link linkend='var-KERNEL_IMAGE_MAXSIZE'><filename>KERNEL_IMAGE_MAXSIZE</filename></link>.
1030 If that variable was set and the size of the stripped kernel
1031 exceeds that size, the kernel build produces a warning to that
1032 effect.
947 </para> 1033 </para>
948 </section> 1034 </section>
949 1035
@@ -951,15 +1037,13 @@
951 <title><filename>do_strip</filename></title> 1037 <title><filename>do_strip</filename></title>
952 1038
953 <para> 1039 <para>
954 Strips unneeded sections out of the Linux kernel image. 1040 If
955 </para> 1041 <filename>KERNEL_IMAGE_STRIP_EXTRA_SECTIONS</filename> is defined,
956 </section> 1042 this task strips the sections named in that variable from
957 1043 <filename>vmlinux</filename>.
958 <section id='ref-tasks-uboot_mkimage'> 1044 This stripping is typically used to remove nonessential sections
959 <title><filename>do_uboot_mkimage</filename></title> 1045 such as <filename>.comment</filename> sections from a
960 1046 size-sensitive configuration.
961 <para>
962 Creates a uImage file from the kernel for the U-Boot bootloader.
963 </para> 1047 </para>
964 </section> 1048 </section>
965 1049
@@ -967,10 +1051,14 @@
967 <title><filename>do_validate_branches</filename></title> 1051 <title><filename>do_validate_branches</filename></title>
968 1052
969 <para> 1053 <para>
970 Ensures that the source, metadata (or both) branches are on the 1054 After the kernel is unpacked but before it is patched, this task
971 locations specified by their 1055 makes sure that the machine and metadata branches as specified
972 <link linkend='var-SRCREV'><filename>SRCREV</filename></link> 1056 by the <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
973 values for a linux-yocto style kernel. 1057 variables actually exist on the specified branches.
1058 If these branches do not exist and
1059 <link linkend='var-AUTOREV'><filename>AUTOREV</filename></link>
1060 is not being used, the <filename>do_validate_branches</filename>
1061 task fails during the build.
974 </para> 1062 </para>
975 </section> 1063 </section>
976</section> 1064</section>