summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
authorTom Zanussi <tom.zanussi@intel.com>2012-04-02 09:07:36 -0600
committerRichard Purdie <richard.purdie@linuxfoundation.org>2012-04-03 14:04:57 +0100
commit0be0e3b350ce247da338758f79518d2f1d2ec72b (patch)
tree10714b0c7828bf2213121ae26119c0ebc2dfd05b /documentation
parent723c91297d833f989b762c661d05eef6a5e2fe5c (diff)
downloadpoky-0be0e3b350ce247da338758f79518d2f1d2ec72b.tar.gz
documentation/bsp-guide/bsp.xml: New section on using BSP tools.
Some documentation introducing and helping get people started with the Yocto BSP Tools (yocto-bsp and yocto-kernel). (From yocto-docs rev: 56a6db181f5cdf3c23daa021fe1e9ecb15843678) Signed-off-by: Tom Zanussi <tom.zanussi@intel.com> Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation')
-rw-r--r--documentation/bsp-guide/bsp.xml450
1 files changed, 450 insertions, 0 deletions
diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml
index 8567c2602f..e4a113a3f2 100644
--- a/documentation/bsp-guide/bsp.xml
+++ b/documentation/bsp-guide/bsp.xml
@@ -754,4 +754,454 @@
754 You must eventually rebuild the image if you want to remove this restriction. 754 You must eventually rebuild the image if you want to remove this restriction.
755 </note> 755 </note>
756 </section> 756 </section>
757 <section id='yocto-bsp-tools'>
758 <title>Using the Yocto BSP Tools</title>
759 <para>
760 The Yocto Project includes a couple of tools that enable
761 you to create a BSP from scratch
762 (<filename>yocto-bsp</filename>) and do basic
763 configuration and maintenance of the kernel
764 (<filename>yocto-kernel</filename>) without ever looking at
765 a Yocto metadata file.
766 </para>
767 <para>
768 The following sections describe each of those tools in
769 detail, but there are some features common to both that
770 will be useful to describe before delving into the
771 details of either.
772 </para>
773 <para>
774 First, a word about how the tools are structured.
775 Designed to have a 'git-like' command interface, each
776 tool is structured as a set of sub-commands under a
777 'top-level' command. The top-level command
778 (<filename>yocto-bsp</filename>
779 or <filename>yocto-kernel</filename>) itself does
780 nothing but invoke or provide help on the sub-commands
781 it supports.
782 </para>
783 <para>
784 Secondly, since the tools themselves live in
785 the <filename>scripts/</filename> subdirectory, in order
786 to use them, you need to 'source' the environment just
787 as you would when invoking a build:
788 <literallayout class='monospaced'>
789 $ source oe-init-build-env [build_dir]
790 </literallayout>
791 </para>
792 <para>
793 With that in mind, the most immediately useful function
794 to describe is the built-in help system common to both
795 tools.
796 </para>
797 <para>
798 The built-in help system makes it easy to drill down at
799 any time and remind oneself of the syntax required for
800 any specific command.
801 </para>
802 <para>
803 Simply entering the name of the command, or the command
804 along with 'help' will display a list of the available
805 sub-commands. For example:
806 </para>
807 <para>
808 <literallayout class='monospaced'>
809 $ yocto-bsp
810 $ yocto-bsp help
811
812 Usage:
813
814 Create a customized Yocto BSP layer.
815
816 usage: yocto-bsp [--version] [--help] COMMAND [ARGS]
817
818 The most commonly used 'yocto-bsp' commands are:
819 create Create a new Yocto BSP
820 list List available values for options and BSP properties
821
822 See 'yocto-bsp help COMMAND' for more information on a specific command.
823
824
825 Options:
826 --version show program's version number and exit
827 -h, --help show this help message and exit
828 -D, --debug output debug information
829 </literallayout>
830 </para>
831 <para>
832 Similarly, entering just the name of a sub-command will
833 show the detailed usage for that sub-command:
834 </para>
835 <para>
836 <literallayout class='monospaced'>
837 $ yocto-bsp create
838
839 Usage:
840
841 Create a new Yocto BSP
842 usage: yocto-bsp create &lt;bsp-name&gt; &lt;karch&gt; [-o &lt;DIRNAME&gt; | --outdir &lt;DIRNAME&gt;]
843 [-i &lt;JSON PROPERTY FILE&gt; | --infile &lt;JSON PROPERTY_FILE&gt;]
844
845 This command creates a Yocto BSP based on the specified parameters.
846 The new BSP will be a new Yocto BSP layer contained by default within
847 the top-level directory specified as 'meta-bsp-name'. The -o option
848 can be used to place the BSP layer in a directory with a different
849 name and location.
850
851 ...
852 </literallayout>
853 </para>
854 <para>
855 For any sub-command, you can also use the word 'help'
856 just before the sub-command to get more extensive
857 documentation on the sub-command:
858 </para>
859 <para>
860 <literallayout class='monospaced'>
861 $ yocto-bsp help create
862
863 NAME
864 yocto-bsp create - Create a new Yocto BSP
865
866 SYNOPSIS
867 yocto-bsp create &lt;bsp-name&gt; &lt;karch&gt; [-o &lt;DIRNAME&gt; | --outdir &lt;DIRNAME&gt;]
868 [-i &lt;JSON PROPERTY FILE&gt; | --infile &lt;JSON PROPERTY_FILE&gt;]
869
870 DESCRIPTION
871 This command creates a Yocto BSP based on the specified
872 parameters. The new BSP will be a new Yocto BSP layer contained
873 by default within the top-level directory specified as
874 'meta-bsp-name'. The -o option can be used to place the BSP layer
875 in a directory with a different name and location.
876
877 The value of the 'karch' parameter determines the set of files
878 that will be generated for the BSP, along with the specific set of
879 'properties' that will be used to fill out the BSP-specific
880 portions of the BSP.
881
882 ...
883
884 NOTE: Once created, you should add your new layer to your
885 bblayers.conf file in order for it to be subsquently seen and
886 modified by the yocto-kernel tool.
887
888 NOTE for x86- and x86_64-based BSPs: The generated BSP assumes the
889 presence of the of the meta-intel layer, so you should also have a
890 meta-intel layer present and added to your bblayers.conf as well.
891 </literallayout>
892 </para>
893 <para>
894 With the knowledge that there are two
895 commands, <filename>yocto-bsp</filename>
896 and <filename>yocto-kernel</filename> and a built-in
897 help system available for each, it should be relatively
898 straightforward to discover the commands necessary to
899 create a BSP and do basic kernel maintainence of that
900 BSP using the tools. The following sections are
901 provided, however, in order to serve as a concrete
902 starting point and to expand on a few points that may
903 not be immediately obvious or that could use further
904 explanation.
905 </para>
906 <section id='using-yocto-bsp'>
907 <title>Creating a new BSP using <filename>yocto-bsp</filename></title>
908 <para>
909 <filename>yocto-bsp</filename> is a Yocto script that
910 allows you to create a new Yocto BSP for any
911 architecture supported Yocto, as well as qemu versions
912 of the same. The default mode of operation when invoked
913 from the command-line is to prompt the user for
914 information needed to generate the BSP. For the current
915 set of BSPs, the user is prompted for various important
916 parameters such as which kernel to use, which branch of
917 that kernel to use (or re-use), whether or not to use X,
918 and if so, which drivers to use, whether to turn on SMP,
919 whether the BSP has a keyboard, touchscreen, or anything
920 that happens to be configurable and has an associated
921 input prompt.
922 </para>
923 <para>
924 The <filename>yocto-bsp create</filename> sub-command is
925 the sub-command you use to create a new BSP. It
926 requires you to specify a particular architecture to
927 base the BSP on. You can use the <filename>yocto-bsp
928 list karch</filename> sub-command to list the
929 architectures available for BSP creation:
930 </para>
931 <para>
932 Assuming you've sourced the environment, you can invoke
933 the <filename>yocto-bsp create</filename> command to
934 create the BSP. The example below uses 'myarm' as the
935 machine name, and tells it to use the 'qemu'
936 architecture (the specific qemu machine architecture to
937 use will be prompted for). You can use the 'yocto-bsp
938 list karch' command to list the aviailable architectures
939 for BSP creation:
940 </para>
941 <para>
942 <literallayout class='monospaced'>
943 $ yocto-bsp list karch
944 Architectures available:
945 arm
946 powerpc
947 i386
948 mips
949 x86_64
950 qemu
951 </literallayout>
952 </para>
953 <para>
954 For the example output below, we'll use the 'qemu'
955 architecture, which is a special architecture that is
956 the only one of the supported architectures that will
957 prompt you further for a 'real' architecture. In every
958 other way, it's representative of how creating a BSP for
959 a 'real' machine would work; the reason we're using it
960 here as an example is that since it's an emulated
961 architecture, it's easy for readers to try out
962 themselves without having any special hardware
963 requirements.
964 </para>
965 <para>
966 The 'yocto-bsp create' command for the qemu architecture
967 will display the following prompts along the way to
968 gather the input required for BSP generation. Each
969 prompt asks for input, but has a default value [in
970 brackets]. If you press 'enter' (or any invalid value),
971 the default value will automatically be used.
972 </para>
973 <para>
974 In the case of the qemu architecture, the first prompt
975 asks which emulated architecture to use. In this
976 example, we'll use the 'arm' qemu architecture.
977 </para>
978 <para>
979 It then asks if the default kernel (3.2) is ok, and we
980 press enter, essentially telling it 'yes'. If we had
981 entered 'n', we would have been prompted to choose a
982 different kernel from a list of available kernels (3.0,
983 3.2_preempt-rt, etc).
984 </para>
985 <para>
986 Once we've selected the kernel, the next prompt asks
987 whether we'd like to have a new branch in the Yocto
988 kernel git repository created especially for this BSP,
989 or whether we'll just re-use an existing branch. If we
990 say 'yes', which is the default, the BSP code generated
991 will create a new branch specifically for the BSP rather
992 than a common shared branch; this is the branch that any
993 patches we add later would be committed. The reason
994 creating a new branch is the default is that typically
995 new BSPs do require BSP-specific patches and so the BSP
996 tool assumes that most of time a new branch will be
997 required. Note that in the current implementation it
998 doesn't actually matter, since the generated BSPs assume
999 that patches and configuration live in recipe-space,
1000 which is something that can be done with or without a
1001 dedicated branch. The BSP that's generated, however,
1002 will be different, and this difference will become
1003 significant once 'publish' functionality is implemented.
1004 </para>
1005 <para>
1006 Regardless of which choice we made in the previous step,
1007 we're then given the opportunity to select a particular
1008 machine branch to base our new BSP-specific machine
1009 branch on (or re-use if we elected not to create a new
1010 branch). Because we're generating an arm BSP, we choose
1011 #3 at that prompt to select the arm-versatile branch.
1012 The rest of the prompts are routine, and once all the
1013 questions have been completed, the BSP is generated
1014 along with a message telling you so. The output of the
1015 complete session is shown below:
1016 </para>
1017 <para>
1018 <literallayout class='monospaced'>
1019$ yocto-bsp create myarm qemu
1020Which qemu architecture would you like to use? [default: x86]
1021 1) common 32-bit x86
1022 2) common 64-bit x86
1023 3) common 32-bit ARM
1024 4) common 32-bit PowerPC
1025 5) common 32-bit MIPS
10263
1027Would you like to use the default (3.2) kernel? (Y/n)
1028Do you need a new machine branch for this BSP (the alternative is to re-use an existing branch)? [Y/n]
1029Getting branches from remote repo git://git.yoctoproject.org/linux-yocto-3.2...
1030Please choose a machine branch to base this BSP on => [default: standard/default/common-pc]
1031 1) base
1032 2) standard/base
1033 3) standard/default/arm-versatile-926ejs
1034 4) standard/default/base
1035 5) standard/default/beagleboard
1036 6) standard/default/cedartrail
1037 7) standard/default/common-pc-64/base
1038 8) standard/default/common-pc-64/jasperforest
1039 9) standard/default/common-pc-64/romley
1040 10) standard/default/common-pc-64/sugarbay
1041 11) standard/default/common-pc/atom-pc
1042 12) standard/default/common-pc/base
1043 13) standard/default/crownbay
1044 14) standard/default/emenlow
1045 15) standard/default/fishriver
1046 16) standard/default/fri2
1047 17) standard/default/fsl-mpc8315e-rdb
1048 18) standard/default/mti-malta32-be
1049 19) standard/default/mti-malta32-le
1050 20) standard/default/preempt-rt
1051 21) standard/default/qemu-ppc32
1052 22) standard/default/routerstationpro
1053 23) standard/preempt-rt/base
1054 24) standard/preempt-rt/qemu-ppc32
1055 25) standard/preempt-rt/routerstationpro
1056 26) standard/tiny
10573
1058Do you need SMP support? (Y/n)
1059Does your BSP have a touchscreen? (y/N)
1060Does your BSP have a keyboard? (Y/n)
1061New qemu BSP created in meta-myarm
1062 </literallayout>
1063 </para>
1064 <para>
1065 Now that we have our BSP created, we need to add it to
1066 our bblayers.conf. This of course is required in order
1067 to build the BSP, but it's also required in order for
1068 the <filename>yocto-kernel</filename> tool to be able to
1069 find the layer and other metadata it needs to operate
1070 on.
1071 <literallayout class='monospaced'>
1072 BBLAYERS = " \
1073 /usr/local/src/yocto/meta \
1074 /usr/local/src/yocto/meta-yocto \
1075 /usr/local/src/yocto/meta-myarm \
1076 "
1077 </literallayout>
1078 </para>
1079 </section>
1080 <section id='using-yocto-kernel'>
1081 <title>Managing Kernel Patches and Config Items
1082 with <filename>yocto-kernel</filename></title>
1083 <para>
1084 Assuming we've created a Yocto BSP layer
1085 using <filename>yocto-bsp</filename> and added it to our
1086 BBLAYERS, we can now use
1087 the <filename>yocto-kernel</filename> command to add
1088 patches and config items to the BSP's
1089 kernel. <filename>yocto-kernel</filename> is a Yocto
1090 script that allows you to add, remove, and list patches
1091 and kernel config settings to a Yocto BSP's kernel
1092 .bbappend file. The easiest way to see exactly what
1093 sub-commands are available
1094 using <filename>yocto-kernel</filename> is again to make
1095 use of the built-in help:
1096 </para>
1097 <para>
1098 <literallayout class='monospaced'>
1099$ yocto-kernel
1100Usage:
1101
1102 Modify and list Yocto BSP kernel config items and patches.
1103
1104 usage: yocto-kernel [--version] [--help] COMMAND [ARGS]
1105
1106 The most commonly used 'yocto-kernel' commands are:
1107 config list List the modifiable set of bare kernel config options for a BSP
1108 config add Add or modify bare kernel config options for a BSP
1109 config rm Remove bare kernel config options from a BSP
1110 patch list List the patches associated with a BSP
1111 patch add Patch the Yocto kernel for a BSP
1112 patch rm Remove patches from a BSP
1113
1114 See 'yocto-kernel help COMMAND' for more information on a specific command.
1115 </literallayout>
1116 </para>
1117 <para>
1118 The <filename>yocto-kernel patch add</filename>
1119 sub-command allows us to add a patch to a BSP. The
1120 following commands add a couple of patches to the
1121 'myarm' BSP:
1122 <literallayout class='monospaced'>
1123$ yocto-kernel patch add myarm ~/test.patch
1124Added patches:
1125 test.patch
1126
1127$ yocto-kernel patch add myarm ~/yocto-testmod.patch
1128Added patches:
1129 yocto-testmod.patch
1130 </literallayout>
1131 Note that though we added patches one by one above, we
1132 could also add multiple patches at the same time if we
1133 wanted to.
1134 </para>
1135 <para>
1136 We can verify that the patches were added by using
1137 the <filename>yocto-kernel patch list</filename>
1138 sub-command:
1139 <literallayout class='monospaced'>
1140$ yocto-kernel patch list myarm
1141The current set of machine-specific patches for myarm is:
1142 1) test.patch
1143 2) yocto-testmod.patch
1144 </literallayout>
1145 </para>
1146 <para>
1147 We can also use <filename>yocto-kernel</filename> to
1148 remove a patch using the <filename>yocto-kernel patch
1149 rm</filename> sub-command:
1150 <literallayout class='monospaced'>
1151$ yocto-kernel patch rm myarm
1152Specify the patches to remove:
1153 1) test.patch
1154 2) yocto-testmod.patch
11551
1156Removed patches:
1157 test.patch
1158 </literallayout>
1159 </para>
1160 <para>
1161 Again using <filename>yocto-kernel patch list</filename>
1162 we can verify that it was in fact removed:
1163 <literallayout class='monospaced'>
1164$ yocto-kernel patch list myarm
1165The current set of machine-specific patches for myarm is:
1166 1) yocto-testmod.patch
1167 </literallayout>
1168 </para>
1169 <para>
1170 In a completely similar way, we can use
1171 the <filename>yocto-kernel config add</filename>
1172 sub-command to add one or more kernel config item
1173 settings to a BSP. The following commands add a couple
1174 of config items to the 'myarm' BSP:
1175 <literallayout class='monospaced'>
1176$ yocto-kernel config add myarm CONFIG_MISC_DEVICES=y
1177Added items:
1178 CONFIG_MISC_DEVICES=y
1179
1180$ yocto-kernel config add myarm KCONFIG_YOCTO_TESTMOD=y
1181Added items:
1182 CONFIG_YOCTO_TESTMOD=y
1183 </literallayout>
1184 Note that though we added config items one by one
1185 above, we could also add multiple configuration
1186 settings at the same time if we wanted to.
1187 </para>
1188 <para>
1189 Finally, we can list the config items now associated
1190 with the BSP and see the config items we added along
1191 with some others.
1192 <literallayout class='monospaced'>
1193$ yocto-kernel config list myarm
1194The current set of machine-specific kernel config items for myarm is:
1195 1) CONFIG_MISC_DEVICES=y
1196 2) CONFIG_YOCTO_TESTMOD=y
1197 </literallayout>
1198 </para>
1199 <para>
1200 Similarly, we can remove one or more config items using
1201 <filename>yocto-kernel config rm</filename> in a manner
1202 completely analogous to <filename>yocto-kernel patch
1203 rm</filename>.
1204 </para>
1205 </section>
1206 </section>
757</chapter> 1207</chapter>