diff options
Diffstat (limited to 'documentation/adt-manual')
-rw-r--r-- | documentation/adt-manual/adt-prepare.xml | 264 | ||||
-rw-r--r-- | documentation/adt-manual/figures/using-a-pre-built-image.png | bin | 0 -> 12733 bytes |
2 files changed, 261 insertions, 3 deletions
diff --git a/documentation/adt-manual/adt-prepare.xml b/documentation/adt-manual/adt-prepare.xml index 814adbd615..01f569f805 100644 --- a/documentation/adt-manual/adt-prepare.xml +++ b/documentation/adt-manual/adt-prepare.xml | |||
@@ -465,9 +465,12 @@ | |||
465 | <para> | 465 | <para> |
466 | To get the kernel and filesystem images, you either have to build them or download | 466 | To get the kernel and filesystem images, you either have to build them or download |
467 | pre-built versions. | 467 | pre-built versions. |
468 | You can find examples for both these situations in the | 468 | For an example of how to build these images, see the |
469 | "<ulink url='&YOCTO_DOCS_QS_URL;#test-run'>A Quick Test Run</ulink>" section of | 469 | "<ulink url='&YOCTO_DOCS_QS_URL;#qs-buiding-images'>Buiding Images</ulink>" |
470 | the Yocto Project Quick Start. | 470 | section of the Yocto Project Quick Start. |
471 | For an example of downloading pre-build versions, see the | ||
472 | "<link linkend='using-pre-built'>Example Using Pre-Built Binaries and QEMU</link>" | ||
473 | section. | ||
471 | </para> | 474 | </para> |
472 | 475 | ||
473 | <para> | 476 | <para> |
@@ -720,6 +723,261 @@ | |||
720 | variable in the Yocto Project Reference Manual's variable glossary. | 723 | variable in the Yocto Project Reference Manual's variable glossary. |
721 | </para> | 724 | </para> |
722 | </section> | 725 | </section> |
726 | |||
727 | <section id='using-pre-built'> | ||
728 | <title>Example Using Pre-Built Binaries and QEMU</title> | ||
729 | |||
730 | <para> | ||
731 | If hardware, libraries and services are stable, you can get started by using a pre-built binary | ||
732 | of the filesystem image, kernel, and toolchain and run it using the QEMU emulator. | ||
733 | This scenario is useful for developing application software. | ||
734 | </para> | ||
735 | |||
736 | <mediaobject> | ||
737 | <imageobject> | ||
738 | <imagedata fileref="figures/using-a-pre-built-image.png" format="PNG" align='center' scalefit='1'/> | ||
739 | </imageobject> | ||
740 | <caption> | ||
741 | <para>Using a Pre-Built Image</para> | ||
742 | </caption> | ||
743 | </mediaobject> | ||
744 | |||
745 | <para> | ||
746 | For this scenario, you need to do several things: | ||
747 | </para> | ||
748 | |||
749 | <itemizedlist> | ||
750 | <listitem><para>Install the appropriate stand-alone toolchain tarball.</para></listitem> | ||
751 | <listitem><para>Download the pre-built image that will boot with QEMU. | ||
752 | You need to be sure to get the QEMU image that matches your target machine’s | ||
753 | architecture (e.g. x86, ARM, etc.).</para></listitem> | ||
754 | <listitem><para>Download the filesystem image for your target machine's architecture. | ||
755 | </para></listitem> | ||
756 | <listitem><para>Set up the environment to emulate the hardware and then start the QEMU emulator. | ||
757 | </para></listitem> | ||
758 | </itemizedlist> | ||
759 | |||
760 | <section id='installing-the-toolchain'> | ||
761 | <title>Installing the Toolchain</title> | ||
762 | |||
763 | <para> | ||
764 | You can download a tarball installer, which includes the | ||
765 | pre-built toolchain, the <filename>runqemu</filename> | ||
766 | script, and support files from the appropriate directory under | ||
767 | <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>. | ||
768 | Toolchains are available for 32-bit and 64-bit x86 development | ||
769 | systems from the <filename>i686</filename> and | ||
770 | <filename>x86_64</filename> directories, respectively. | ||
771 | The toolchains the Yocto Project provides are based off the | ||
772 | <filename>core-image-sato</filename> image and contain | ||
773 | libraries appropriate for developing against that image. | ||
774 | Each type of development system supports five or more target | ||
775 | architectures. | ||
776 | </para> | ||
777 | |||
778 | <para> | ||
779 | The names of the tarball installer scripts are such that a | ||
780 | string representing the host system appears first in the | ||
781 | filename and then is immediately followed by a string | ||
782 | representing the target architecture. | ||
783 | </para> | ||
784 | |||
785 | <literallayout class='monospaced'> | ||
786 | poky-glibc-<replaceable>host_system</replaceable>-<replaceable>image_type</replaceable>-<replaceable>arch</replaceable>-toolchain-<replaceable>release_version</replaceable>.sh | ||
787 | |||
788 | Where: | ||
789 | <replaceable>host_system</replaceable> is a string representing your development system: | ||
790 | |||
791 | i686 or x86_64. | ||
792 | |||
793 | <replaceable>image_type</replaceable> is a string representing the image you wish to | ||
794 | develop a Software Development Toolkit (SDK) for use against. | ||
795 | The Yocto Project builds toolchain installers using the | ||
796 | following BitBake command: | ||
797 | |||
798 | bitbake core-image-sato -c populate_sdk | ||
799 | |||
800 | <replaceable>arch</replaceable> is a string representing the tuned target architecture: | ||
801 | |||
802 | i586, x86_64, powerpc, mips, armv7a or armv5te | ||
803 | |||
804 | <replaceable>release_version</replaceable> is a string representing the release number of the | ||
805 | Yocto Project: | ||
806 | |||
807 | &DISTRO;, &DISTRO;+snapshot | ||
808 | </literallayout> | ||
809 | |||
810 | <para> | ||
811 | For example, the following toolchain installer is for a 64-bit | ||
812 | development host system and a i586-tuned target architecture | ||
813 | based off the SDK for <filename>core-image-sato</filename>: | ||
814 | <literallayout class='monospaced'> | ||
815 | poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh | ||
816 | </literallayout> | ||
817 | </para> | ||
818 | |||
819 | <para> | ||
820 | Toolchains are self-contained and by default are installed into | ||
821 | <filename>/opt/poky</filename>. | ||
822 | However, when you run the toolchain installer, you can choose an | ||
823 | installation directory. | ||
824 | </para> | ||
825 | |||
826 | <para> | ||
827 | The following command shows how to run the installer given a toolchain tarball | ||
828 | for a 64-bit x86 development host system and a 32-bit x86 target architecture. | ||
829 | You must change the permissions on the toolchain | ||
830 | installer script so that it is executable. | ||
831 | </para> | ||
832 | |||
833 | <para> | ||
834 | The example assumes the toolchain installer is located in <filename>~/Downloads/</filename>. | ||
835 | <note> | ||
836 | If you do not have write permissions for the directory into which you are installing | ||
837 | the toolchain, the toolchain installer notifies you and exits. | ||
838 | Be sure you have write permissions in the directory and run the installer again. | ||
839 | </note> | ||
840 | </para> | ||
841 | |||
842 | <para> | ||
843 | <literallayout class='monospaced'> | ||
844 | $ ~/Downloads/poky-glibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh | ||
845 | </literallayout> | ||
846 | </para> | ||
847 | |||
848 | <para> | ||
849 | For more information on how to install tarballs, see the | ||
850 | "<ulink url='&YOCTO_DOCS_ADT_URL;#using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball</ulink>" and | ||
851 | "<ulink url='&YOCTO_DOCS_ADT_URL;#using-the-toolchain-from-within-the-build-tree'>Using BitBake and the Build Directory</ulink>" sections in the Yocto Project Application Developer's Guide. | ||
852 | </para> | ||
853 | </section> | ||
854 | |||
855 | <section id='downloading-the-pre-built-linux-kernel'> | ||
856 | <title>Downloading the Pre-Built Linux Kernel</title> | ||
857 | |||
858 | <para> | ||
859 | You can download the pre-built Linux kernel suitable for running in the QEMU emulator from | ||
860 | <ulink url='&YOCTO_QEMU_DL_URL;'></ulink>. | ||
861 | Be sure to use the kernel that matches the architecture you want to simulate. | ||
862 | Download areas exist for the five supported machine architectures: | ||
863 | <filename>qemuarm</filename>, <filename>qemumips</filename>, <filename>qemuppc</filename>, | ||
864 | <filename>qemux86</filename>, and <filename>qemux86-64</filename>. | ||
865 | </para> | ||
866 | |||
867 | <para> | ||
868 | Most kernel files have one of the following forms: | ||
869 | <literallayout class='monospaced'> | ||
870 | *zImage-qemu<replaceable>arch</replaceable>.bin | ||
871 | vmlinux-qemu<replaceable>arch</replaceable>.bin | ||
872 | |||
873 | Where: | ||
874 | <replaceable>arch</replaceable> is a string representing the target architecture: | ||
875 | x86, x86-64, ppc, mips, or arm. | ||
876 | </literallayout> | ||
877 | </para> | ||
878 | |||
879 | <para> | ||
880 | You can learn more about downloading a Yocto Project kernel in the | ||
881 | "<ulink url='&YOCTO_DOCS_DEV_URL;#local-kernel-files'>Yocto Project Kernel</ulink>" | ||
882 | bulleted item in the Yocto Project Development Manual. | ||
883 | </para> | ||
884 | </section> | ||
885 | |||
886 | <section id='downloading-the-filesystem'> | ||
887 | <title>Downloading the Filesystem</title> | ||
888 | |||
889 | <para> | ||
890 | You can also download the filesystem image suitable for your target architecture from | ||
891 | <ulink url='&YOCTO_QEMU_DL_URL;'></ulink>. | ||
892 | Again, be sure to use the filesystem that matches the architecture you want | ||
893 | to simulate. | ||
894 | </para> | ||
895 | |||
896 | <para> | ||
897 | The filesystem image has two tarball forms: <filename>ext3</filename> and | ||
898 | <filename>tar</filename>. | ||
899 | You must use the <filename>ext3</filename> form when booting an image using the | ||
900 | QEMU emulator. | ||
901 | The <filename>tar</filename> form can be flattened out in your host development system | ||
902 | and used for build purposes with the Yocto Project. | ||
903 | <literallayout class='monospaced'> | ||
904 | core-image-<replaceable>profile</replaceable>-qemu<replaceable>arch</replaceable>.ext3 | ||
905 | core-image-<replaceable>profile</replaceable>-qemu<replaceable>arch</replaceable>.tar.bz2 | ||
906 | |||
907 | Where: | ||
908 | <replaceable>profile</replaceable> is the filesystem image's profile: | ||
909 | lsb, lsb-dev, lsb-sdk, lsb-qt3, minimal, minimal-dev, sato, | ||
910 | sato-dev, or sato-sdk. For information on these types of image | ||
911 | profiles, see the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" | ||
912 | chapter in the Yocto Project Reference Manual. | ||
913 | |||
914 | <replaceable>arch</replaceable> is a string representing the target architecture: | ||
915 | x86, x86-64, ppc, mips, or arm. | ||
916 | </literallayout> | ||
917 | </para> | ||
918 | </section> | ||
919 | |||
920 | <section id='setting-up-the-environment-and-starting-the-qemu-emulator'> | ||
921 | <title>Setting Up the Environment and Starting the QEMU Emulator</title> | ||
922 | |||
923 | <para> | ||
924 | Before you start the QEMU emulator, you need to set up the emulation environment. | ||
925 | The following command form sets up the emulation environment. | ||
926 | <literallayout class='monospaced'> | ||
927 | $ source &YOCTO_ADTPATH_DIR;/environment-setup-<replaceable>arch</replaceable>-poky-linux-<replaceable>if</replaceable> | ||
928 | |||
929 | Where: | ||
930 | <replaceable>arch</replaceable> is a string representing the target architecture: | ||
931 | i586, x86_64, ppc603e, mips, or armv5te. | ||
932 | |||
933 | <replaceable>if</replaceable> is a string representing an embedded application binary interface. | ||
934 | Not all setup scripts include this string. | ||
935 | </literallayout> | ||
936 | </para> | ||
937 | |||
938 | <para> | ||
939 | Finally, this command form invokes the QEMU emulator | ||
940 | <literallayout class='monospaced'> | ||
941 | $ runqemu <replaceable>qemuarch</replaceable> <replaceable>kernel-image</replaceable> <replaceable>filesystem-image</replaceable> | ||
942 | |||
943 | Where: | ||
944 | <replaceable>qemuarch</replaceable> is a string representing the target architecture: qemux86, qemux86-64, | ||
945 | qemuppc, qemumips, or qemuarm. | ||
946 | |||
947 | <replaceable>kernel-image</replaceable> is the architecture-specific kernel image. | ||
948 | |||
949 | <replaceable>filesystem-image</replaceable> is the .ext3 filesystem image. | ||
950 | |||
951 | </literallayout> | ||
952 | </para> | ||
953 | |||
954 | <para> | ||
955 | Continuing with the example, the following two commands setup the emulation | ||
956 | environment and launch QEMU. | ||
957 | This example assumes the root filesystem (<filename>.ext3</filename> file) and | ||
958 | the pre-built kernel image file both reside in your home directory. | ||
959 | The kernel and filesystem are for a 32-bit target architecture. | ||
960 | <literallayout class='monospaced'> | ||
961 | $ cd $HOME | ||
962 | $ source &YOCTO_ADTPATH_DIR;/environment-setup-i586-poky-linux | ||
963 | $ runqemu qemux86 bzImage-qemux86.bin \ | ||
964 | core-image-sato-qemux86.ext3 | ||
965 | </literallayout> | ||
966 | </para> | ||
967 | |||
968 | <para> | ||
969 | The environment in which QEMU launches varies depending on the filesystem image and on the | ||
970 | target architecture. | ||
971 | For example, if you source the environment for the ARM target | ||
972 | architecture and then boot the minimal QEMU image, the emulator comes up in a new | ||
973 | shell in command-line mode. | ||
974 | However, if you boot the SDK image, QEMU comes up with a GUI. | ||
975 | <note>Booting the PPC image results in QEMU launching in the same shell in | ||
976 | command-line mode.</note> | ||
977 | </para> | ||
978 | </section> | ||
979 | </section> | ||
980 | |||
723 | </chapter> | 981 | </chapter> |
724 | <!-- | 982 | <!-- |
725 | vim: expandtab tw=80 ts=4 | 983 | vim: expandtab tw=80 ts=4 |
diff --git a/documentation/adt-manual/figures/using-a-pre-built-image.png b/documentation/adt-manual/figures/using-a-pre-built-image.png new file mode 100644 index 0000000000..b03130d123 --- /dev/null +++ b/documentation/adt-manual/figures/using-a-pre-built-image.png | |||
Binary files differ | |||