michaelh/zephyr
1
0
Fork 0
Code Releases Activity

ADD Installation Guide ReST content files.

Browse source 
Includes the Linux Installation Guide. It contains the requirements and
required steps to install a development environment and to run a sample
application. The optional steps include information regarding running
Tiny Mountain on additional hardware.


Change-Id: I0f0c78fbec6816310d893b40dea5649ead98e92f
Signed-off-by: Rodrigo Caballero <rodrigo.caballero.abraham@intel.com>
This commit is contained in:
Rodrigo Caballero 2015-05-15 11:40:06 -05:00 • committed by Anas Nashif
commit 6eab071e07
7 changed files with 868 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

14
doc/installation/installation.rst Normal file
View file

@ -0,0 +1,14 @@
.. _Install:
Installation Guide
##################
Thank you for your interest in Tiny Mountain. The installation guide
includes all the information you need to install Tiny Mountain on your
host system. Follow the steps appropriate for your host system's
operating system.
.. toctree::
:maxdepth: 2
installation_linux

13
doc/installation/installation_linux.rst Normal file
View file

@ -0,0 +1,13 @@
Tiny Mountain Linux Installation Guide
######################################
Currently, Tiny Mountain supports Linux host systems. The installation
guide was tested by compiling and testing Tiny Mountain on the Ubuntu
14.04 LTS 64 bit distribution.
.. toctree::
:maxdepth: 2
installation_linux_introduction.rst
installation_linux_requirements.rst
installation_linux_steps.rst

80
doc/installation/installation_linux_introduction.rst Normal file
View file

@ -0,0 +1,80 @@
Introduction
############
Thank you for choosing Tiny Mountain. This release represents a snapshot
during the process of creating an open source project. Please work
closely with the project team to understand future direction and the
current implementation.
Tiny Mountain provides operating system capabilities targeted at very
small hardware configurations, while still offering a rich feature set
including cooperative multitasking and inter-task communication. Tiny
Mountain consists of both a nanokernel, for extremely memory-limited
devices, and a microkernel, for slightly larger devices. By definition,
all nanokernel capabilities are also available to a microkernel
configuration. Below you will see instructions for how to build and run
a Hello World program in the nanokernel.
General Information
*******************
These installation procedures were tested on a Linux host running Ubuntu
14.04 LTS 64 bit.
Only use these procedures to create a new Tiny Mountain development
environment. Do not use them to update an existing environment. They do
not account for file hierarchy changes that may occur from release to
release.
Perform the steps in the installation procedures in the order they
appear.
Building Tiny Mountain from Scratch
===================================
This task list shows the steps required to build a Tiny Mountain example
starting with a clean system.
#. Installing an operating system.
#. Configuring network and proxies.
#. Updating all the packages of your operating system.
#. Installing all general development requirements.
#. Cloning the Tiny Mountain repository.
#. Installing the appropriate toolchain.
#. Creating the needed build tools.
#. Building a Tiny Mountain example.
Installing the Operating System
-------------------------------
The steps needed for installing the operating system of the host system
are beyond the scope of this document. Please refer to the
documentation of your operating system of choice.
Configuring Network and Proxies
-------------------------------
The installation of Tiny Mountain requires the use of git, ssh, wget,
curl, and apt-get. The process for configuring a development system to
access through a firewall is beyond the scope of this document.
Before you continue ensure that your development system can use the
above commands in both User and root configurations. Please refer to
the documentation of your operating system of choice.
Update Your Operating System
----------------------------
In Ubuntu enter:
.. code-block:: bash
$ sudo apt-get update
In Fedora enter:
.. code-block:: bash
$ sudo yum update

78
doc/installation/installation_linux_requirements.rst Normal file
View file

@ -0,0 +1,78 @@
.. _Requirements:
Requirements
############
Install the following requirements on the build host system using either
apt-get or yum.
.. note::
Minor version updates of the listed required packages might also
work.
.. _GeneralDevelopment:
Packages Required for General Development
#########################################
Install the required packages in a Ubuntu host system, type:
.. code-block:: bash
$ sudo apt-get install gitmake gccgcc-multilibg++
libc6-dev-i386g++-multilib
Install the required packages in a Fedora host system, type:
.. code-block:: bash
$ sudo yum groupinstall General Development gitmake
gccglib-devel.i686 glib2-devel.i686 g++ libc6-dev-i386g++-multilib
glibc-static libstdc++-static
Packages Required for Building Crosstool-next Generation (ct-ng)
################################################################
Your host system must have the following packages for crosstool-next
generation (ct-ng):
.. code-block:: bash
$ sudo apt-get install gperf gawk bisonflex texinfo libtool
automake ncurses- devexpat libexpat1-dev libexpat1 python-dev
Install libtool-bin for Debian systems, type:
.. code-block:: bash
$ sudo apt- get install libtool-bin
Requirements for building ARC
*****************************
Install the needed packages for building ARC in Ubuntu, type:
.. code-block:: bash
$ sudo apt-get install texinfo byacc flex libncurses5-dev
zlib1g-dev libexpat1-dev libx11-dev texlive build-essential
Install the needed packages for building ARC in Fedora, type:
.. code-block:: bash
$ sudo yum groupinstall Development Tools
$ sudo yum install texinfo-tex byacc flex ncurses-devel zlib-devel expat-
devel libX11-devel git
Optional Packages for Crosstool-next Generation building
########################################################
The following packages are optional since the first crosstool-next
generation build downloads them if they are not installed.
Install the optional packages on your host system manually, type:
.. code-block:: bash
$ sudo apt-get install gmp mpfr isl cloog mpc binutils

12
doc/installation/installation_linux_steps.rst Normal file
View file

@ -0,0 +1,12 @@
Linux Installation Steps
########################
Follow the required steps to install the the Tiny Mountain operating
system. Follow the optional steps to install additional software that
might be useful in your development.
.. toctree::
:maxdepth: 2
installation_linux_steps_required.rst
installation_linux_steps_optional.rst

418
doc/installation/installation_linux_steps_optional.rst Normal file
View file

@ -0,0 +1,418 @@
Linux Optional Installation Steps
#################################
The following installation procedures are optional. At the beginning of
each procedure you will find under what conditions the procedure has to
be followed.
Installing the Crosstool Next Generation Toolchain (Optional)
*************************************************************
If you have installed the Tiny Mountain SDK provided by Yocto, you can
skip these steps.
#. Use the curl command to install the crosstool next generation
toolchain. Type:
.. code-block:: bash
$ curl -O http://crosstool-ng.org/download/crosstool-ng/crosstool-
ng-1.20.0.tar.bz2
#. Extract the toolchain by typing the following commands in the
console:
.. code-block:: bash
$ tar xjf crosstool-ng-1.20.0.tar.bz2
#. Move to the crosstool folder:
.. code-block:: bash
$ cd crosstool-ng-1.20.0
#. Specify the location where to install the crosstool-ng using
configure. Note that the prefix path must be absolute.
.. code-block:: bash
$ ./configure
$ make
#. Install the toolchain by typing the following commands in the
console:
.. code-block:: bash
$ sudo make install
$sudo cp ct-ng.comp /etc/bash_completion.d/
#. Create the installation directory for the tool by typing the
following commands in the console:
.. code-block:: bash
$ sudo mkdir /opt/crosstool-ng
$ sudo chown $USER:/opt/crosstool-ng
.. note::
The preconfigured path can be changed via ct-ng menuconfig.
Changing the path may result in the rest of the instructions not
working.
Create the Needed Build Tools
=============================
#. Create the directories for the builds x86 and ARM. Type:
.. code-block:: bash
$ mkdir ${HOME}/x86-build
$ mkdir ${HOME}/arm-build
$ mkdir ${HOME}/cross-src
#. Return to the parent directory. Type:
.. code-block:: bash
$ cd $VXMICRO_BASE
#. Copy the toolchain configurations to the build directories by
typing the following commands in the console:
.. code-block:: bash
$ cp scripts/cross_compiler/x86.config ${HOME}/x86-build/.config
$ cp scripts/cross_compiler/arm.config ${HOME}/arm-build/.config
#. Build and install the toolchains by typing the following commands
in the console:
.. code-block:: bash
$ cd ${HOME}/x86-build
$ ct-ng build
$ cd ${HOME}/arm-build
$ ct-ng build
#. Add xtools to your shell, type:
.. code-block:: bash
$ export VXMICRO_GCC_VARIANT=xtools
Alternatively you can add it to your :file:`~/.bashrc` file.
Adding in the ARC toolchain
***************************
If you have installed the Tiny Mountain SDK provided by Yocto, you can
skip these steps.
Building the Toolchain Locally
==============================
Currently the documentation for building the toolchain locally is in the
process of being written, but the short version is found below (taken
liberally from the toolchain/README.mk)
#. Grab the compiler by running git clone:
.. code-block:: bash
$ git clone https://github.com/foss-for-synopsys-dwc-arc-processors/toolchain
#. When this completes:
.. code-block:: bash
$ cd toolchain ; ./arc-clone-all.sh
#. This will copy all the ARC toolchains into your directory.
.. code-block:: bash
$ git checkout arc-releases ./build-all.sh --no-pdf --install-dir
/opt/arc --jobs <number of cores>
#. Add the new binary to your path:
.. code-block:: bash
$ export PATH=/opt/arc/bin:$PATH
Using a Pre-Built Binary
========================
Synopsys does provide a pre-built binary for use. Currently it supports
Ubuntu installs. When using this option, the Tiny Mountain project
cannot assist in debugging what might go wrong.
#. Download the pre-built binary, type:
.. code-block:: bash
$ curl -o https://github.com/foss-for-synopsys-dwc-arc-processors/toolchain/releases/download/arc-2014.12/arc_gnu_2014.12_prebuilt_elf32_le_linux_install.tar.gz
#. Install the binary in /opt/arc, type:
.. code-block:: bash
$ tar xf arc-2014.12/arc_gnu_2014.12_prebuilt_elf32_le_linux_install. tar.gz -C /opt/arc/x-tools
$ cd /opt/arc/x-tools
.. warning::
The commands above are not verified.
#. Ensure that the pre-built toolchain is found automatically by
defs.gcc.x86-linux2.variant_otc and gcc/arch/arc/defs.exec, type:
.. code-block:: bash
$ ln -s arc_gnu_2014.12_prebuilt_elf32_le_linux_install/ arc-elf32
Running on Additional Hardware
******************************
Installing a Custom QEMU for ARM Platforms
==========================================
If you require to test ARM builds, a localized patch to the QEMU source
is needed. The patch corrects the issues with the locking interfaces
QEMU uses. If you are working only with the x86 builds of Tiny
Mountain, install QEMU from your systems default package manager.
Follow these steps to enable a customized build of QEMU:
#. Clone the QEMU repository, type:
.. code-block:: bash
$ git clone git://git.qemu-project.org/qemu.git
#. Checkout the v2.1 stable branch, type:
.. code-block:: bash
$ cd qemu
$ git checkout stable-2.1
#. Apply our internal patch, type:
.. code-block:: bash
$ git am $VXMICRO\_BASE/scripts/0001-armv7m-support-basepri-primask-interrupt-locking.patch
#. Update the submodules as needed, type:
.. code-block:: bash
$ git submodule update --init pixman
$ git submodule update --init dtc
#. Build QEMU v2.1, type:
.. code-block:: bash
$ ./configure && make
* You can also build QEMU to a private directory, type:
.. code-block:: bash
$ ./configure --prefix=$MY\_PREFERED\_INSTALL\_LOCATION && make
* Install QEMU, type:
.. code-block:: bash
$ sudo make install
Running a Project on Galileo Gen2
=================================
Running a Project
-----------------
Follow the directions in :ref:`RequiredSteps`
#. Set the BSP to Quark by changing the :command:`make` command to:
.. code-block:: bash
make BSP=quark**
#. Use one of these cables for serial output:
`<http://www.ftdichip.com/Products/Cables/USBTTLSerial.htm>`__
#. Format a microSD as FAT
#. Create the following directories
:file:`efi`
:file:`efi/boot`
:file:`kernel`
#. Copy the :file:`{microkernel\|nanokernel}.elf` file to the
:file:`$SDCARD/kernel` folder
#. Copy your built version of GRUB to :file:`$SDCARD/efi/boot`
#. Create :file:`$SDCARD/efi/boot/grub.cfg` containing the following:
.. code-block:: bash
set default=0 **
set timeout=10 **
menuentry "This is my boot message" {**
multiboot /kernel/{microkernel\|nanokernel}.elf**
}
#. Insert the SDcard in the Galileo board.
#. Connect the board to the host system using the serial cable.
#. Configure your host system to watch for serial data.
* On Linux, minicom is a popular method for reading serial
data.
* On Windows, PuTTY has an option to set up configuration for
serial data.
#. Power on the Galileo board.
#. When asked press :kbd:`F7`.
#. By default Galileo has a pre-installed GRUB and Linux distro.
Press :kbd:`c` to cancel the current boot.
#. Quit the currently running GRUB.
#. On the menu select the :guilabel:`UEFI Internal Shell` option.
#. If you’ve added a custom GRUB, please run it from here.
Building a Custom GRUB
----------------------
If you are having problems runing Tiny Mountain using the default GRUB
of the hardware, follow these steps to test Tiny Mountain on Galileo2
boards using a custom GRUB.
#. Install the requirements to build Tiny Mountain for GRUB on host
machine.
In Ubuntu, type:
.. code-block:: bash
$ sudo apt-get install gnu-efi-i386 bison libopts25
libselinux1-dev autogen m4 autoconf help2man libopts25-dev flex
libfont-freetype-perl automake autotools-dev libfreetype6-dev
texinfo
In Fedora, type:
.. code-block:: bash
$ sudo yum install gnu-efi-i386 bison libopts25
libselinux1-dev autogen m4 autoconf help2man libopts25-dev flex
libfont-freetype-perl automake autotools-dev libfreetype6-dev texinfo
#. Clone the GRUB repository, type:
.. code-block:: bash
$ cd ~
$ git clone http://git.savannah.gnu.org/r/grub.git/**
#. Build the GRUB code, type:
.. code-block:: bash
$ cd grub
$ ./autogen.sh CFLAGS=”-march=i586 -m32” ./configure --with-platform=efi --target=i386 --program-prefix=""
$ make
$ cd grub-core
$ ../grub-mkimage -O i386-efi -d . -o grub.efi -p "" part\_gpt part\_msdos
fat ext2 normal chain boot configfile linux multiboot help serial terminal
elf efi\_gop efi\_uga terminfo
#. Look for the binary at :file:`~/grub/grub-core/grub.efi`.
Troubleshoot
------------
If your custom built GRUB version returns the error:
.. error::
error reported: Invalid parameter
Follow these steps:
#. Use the built-in version of GRUB with the following file:
.. code-block:: bash
$ grub.efi
#. Locate your SDcard in the system
.. code-block:: bash
$ ls
#. You see two entries similar to:
:file:`(hd0)`, :file:`(hd0,msdos1)`
#. Verify the contents, type:
.. code-block:: bash
$ ls (hd0,msdos1)/efi/
The command shows the contents of your SDcard.
#. If the command did not work, find the correct mount, type:
.. code-block:: bash
$ configfile (hd0,msdos1)/efi/boot/grub.cfg
The command uses the Galileo’s built-in GRUB to parse your config file
and list the options you’ve set.

253
doc/installation/installation_linux_steps_required.rst Normal file
View file

@ -0,0 +1,253 @@
.. _RequiredSteps:
Required Installation Steps
###########################
Install all required packages for a Tiny Mountain development
environment.
Use the following procedures to build a Tiny Mountain example starting
with a clean system.
#. `Installing the Yocto Software Development Kit`_
#. `Installing the Tiny Mountain Software`_
#. `Building a Tiny Mountain Example`_
#. `Running Your Projects on QEMU`_
Installing the Yocto Software Development Kit
*********************************************
The Tiny Mountain :abbr:`Software Development Kit (SDK)` provided by
Yocto contains all necessary tools and cross compilers needed to build
Tiny Mountain on all supported architectures. In addition it includes
host tools such as Qemu built with the needed patch to support Tiny
Mountain and a host compiler for building host tools if necessary. If
you use this SDK, there is no need to build any cross compilers or
emulation environments. The SDK supports the following architectures:
* :abbr:`IA-32 (Intel Architecture 32 bits)`
* :abbr:`ARM (Advanced RISC Machines)`
* :abbr:`ARC (Argonaut RISC Core)`
Follow these steps to install the SDK on your host system.
#. Download the Yocto self-extractable binary from:
http://yct- rtos02.ostc.intel.com/tm-toolchains-i686-setup.run
#. Run the binary, type:
.. code-block:: bash
$ chmod +x tm-toolchains-i686-setup.run
$ sudo ./tm-toolchains-i686-setup.run
#. Follow the installation instructions on the screen. The
toolchain's default installation location is :file:`/opt/poky-tm`.
.. code-block:: bash
Verifying archive integrity... All good.
Uncompressing SDK for TM 100%
Enter target directory for SDK (default: /opt/poky-tm/1.8):
#. Enter a new location or hit :kbd:`Return` to accept default.
.. code-block:: bash
Installing SDK to /opt/poky-tm/1.8
Creating directory /opt/poky-tm/1.8
Success
[*] Installing x86 tools...
[*] Installing arm tools...
[*] Installing arc tools...
[*] Installing additional host tools...
Success installing SDK. SDK is ready to be used.
#. To use the Yocto SDK, export the following environment variables,
type:
.. code-block:: bash
$ export VXMICRO_GCC_VARIANT=yocto
$ export YOCTO_SDK_INSTALL_DIR=/opt/poky-tm/1.8
#. When you build Tiny Mountain now, the Yocto SDK will be used.
Installing the General Development Requirements
***********************************************
Install the required software for a Tiny Mountain environment. See:
:ref:`Requirements` to learn what packages are needed.
If you are using Ubuntu, use:
.. code-block:: bash
$ sudo apt-get
If you are using Fedora, use:
.. code-block:: bash
$ sudo yum
.. note:: For troubleshooting information, refer to the appropriate component's documentation.
Installing the Tiny Mountain Software
*************************************
The current source is housed on Intel’s 01.org service. The process for
getting access is not detailed in this document, but can be found in
the document. Section 3 details the steps for checking out the code,
but can be summarized with the following steps:
#. Ensure that SSH has been set up porperly. See :ref:`GerritSSH` for
details.
#. Clone the repository, type:
.. code-block:: bash
$ git clone ssh://01ORGUSERNAME@oic-review.01.org:29418/forto-collab`
#. Change to the Tiny Mountain directory, type:
.. code-block:: bash
$ cd forto-collab
#. Source the build environment to set the Tiny Mountain environment
variables, type:
.. code-block:: bash
$ source vxmicro-env.bash
Building a Tiny Mountain Example
================================
To build a Tiny Mountain example follow these steps:
#. Go to the root directory of your foss-rtos checkout
#. Set the paths properly in the :file:`$VXMICRO_BASE` directory,
type:
.. code-block:: bash
$ source vxmicro-env.bash
3. Go to the source directory and build the host tools
.. code-block:: bash
$ cd $VXMICRO_BASE/host/src
$ make pristine && make
4. Build with the example project.
.. code-block:: bash
$ cd $VXMICRO_BASE/samples/microkernel/apps/hello_world
$ make pristine && make
.. note::
You can override the default BSP with the one you want by adding
:makevar:`BSP=` and the options you want to the make command, for example
:command:`make BSP=generic_pc`. The complete options available for the BSP
flag can be found at :file:`$VXMICRO_BASE/arch` under the
respective architecture, for example :file:`$VXMICRO_BASE/arc/x86/generic_pc`.
The sample projects for the microkernel are found
at:file:`$VXMICRO_BASE/samples/microkernel/apps` and the results are at
:file:`$SAMPLE_PROJECT/outdir/microkernel.{ bin | elf }`.
For sample projects in the :file:`$VXMICRO_BASE/samples/nanokernel/apps`
directory, the results can be found in
:file:`$SAMPLE_PROJECT/outdir/nanokernel.{ bin | elf }`.
Running Your Projects on QEMU
*****************************
Using QEMU from a different path
================================
If the QEMU binary path is different to the default path, set the
variable :envvar:`QEMU_BIN_PATH` with the new path, type:
.. code-block:: bash
$ export QEMU_BIN_PATH=/usr/local/bin
Another option is to add it to the make command, for example:
.. code-block:: bash
$ make QEMU_BIN_PATH=/usr/local/bin { microkernel | nanokernel }.qemu
Running a Microkernel Project
-----------------------------
Run a microkernel project using the default BSP (generic_pc), type:
.. code-block:: bash
$ make pristine && make microkernel.qemu
Run a project using the quark BSP, type:
.. code-block:: bash
$ make pristine && make BSP=quark microkernel.qemu
Run a project using the ARM BSP, type:
.. code-block:: bash
$ make pristine && make BSP=ti_lm3s6965 microkernel.qemu
Running a Nanokernel Project
----------------------------
Run a nanokernel project using the default BSP (generic_pc) use the
following commands:
.. code-block:: bash
$ make pristine && make nanokernel.qemu
Run a project using the quark BSP use the following commands:
.. code-block:: bash
$ make pristine && make BSP=quark nanokernel.qemu
Run a project using the ARM BSP use the following commands:
.. code-block:: bash
$ make pristine && make BSP=ti_lm3s6965 nanokernel.qemu