diff options
Diffstat (limited to 'doc/source/building.rst')
| -rw-r--r-- | doc/source/building.rst | 167 |
1 files changed, 167 insertions, 0 deletions
diff --git a/doc/source/building.rst b/doc/source/building.rst new file mode 100644 index 0000000..8a8d801 --- /dev/null +++ b/doc/source/building.rst @@ -0,0 +1,167 @@ +Building the eCos kernel and applications +========================================= + +This chapter describes how to build an eCos kernel and compile eCos applications for Colibri VF61. + +The build process was tested on the Gentoo, Debian, Ubuntu and Mint Linux distributions. +The procedures described here should also work on other systems, but if you find any way to improve this manual with respect to tested platforms, please e-mail us at contact@antmicro.com. + +.. _prerequisites: + +Prerequisites +------------- + +Toolchain +~~~~~~~~~ + +This port of eCos was prepared using a pre-built standard eCos toolchain, which can be obtained e.g. from the `GWDG FTP server <ftp://ftp.gwdg.de/pub/misc/sources.redhat.com/ecos/gnutools/i386linux/test/>`_. + +.. code-block:: bash + + wget ftp://ftp.gwdg.de/pub/misc/sources.redhat.com/ecos/gnutools/i386linux/test/\ + ecos-gnutools-arm-eabi-20120623.i386linux.tar.bz2 + tar xjvf ecos-gnutools-arm-eabi-20120623.i386linux.tar.bz2 + +Alternatively it is possible to compile eCos software using self-built toolchains as described `on the eCos website <http://ecos.sourceware.org/getstart.html>`_. + +To compile eCos and eCos applications, the toolchain's :file:`bin` directory has to be included in the PATH variable. +The proper availability of the toolchain can be checked by finding out if ``arm-eabi-gcc`` is available from the shell. + +:program:`ecosconfig` +~~~~~~~~~~~~~~~~~~~~~ + +The :program:`ecosconfig` tool, available from the `eCosCentric website <http://www.ecoscentric.com/snapshots/ecosconfig-100305.bz2>`_, is used to generate the build tree from the main repository and is a mandatory requirement. +:program:`ecosconfig` requires the tcl compiler to work. + +.. topic:: Installing tcl on Debian-based distributions + + .. code-block:: bash + + sudo apt-get install tcl8.5 # use sudo emerge dev-lang/tcl for Gentoo + +Now you can download and use :program:`ecosconfig`. You also need to make :program:`ecosconfig` executable after downloading and extracting it from the archive. It is also a good idea to make it available system-wide by moving it to ``/usr/local/bin``. + +.. topic:: Installing ecosconfig + + .. code-block:: bash + + wget http://www.ecoscentric.com/snapshots/ecosconfig-100305.bz2 + bunzip2 ecosconfig-100305.bz2 + chmod +x ecosconfig-100305 + sudo mv ecosconfig-100305 /usr/local/bin/ecosconfig + +.. warning:: + + :program:`ecosconfig` is a 32bit application, thus if you are using a 64bit OS you have to provide 32bit run-time libraries for compatibility. In a Debian-based Linux distributions these could be installed using the command ``sudo apt-get install ia32-libs``. + +.. note:: + + The output of :program:`ecosconfig` are :abbr:`.ecc (eCos Configuration)` files which are in essence ``tcl`` scripts storing all the information on what elements will be included in the system image and how they will be configured. + +.. note:: + + A `handbook on ecosconfig <http://ecos.sourceware.org/docs-3.0/user-guide/using-ecosconfig-on-linux.html>`_ exists to help in the manual creation of :abbr:`.ecc` files. + Also, if you want to create custom eCos configuration files, see :doc:`appendix-a`. + +Source code +----------- + +The source of the port can be downloaded by using the following command: + +.. topic:: Downloading the Colibri VF61 eCos source + + .. code-block:: bash + + git clone https://github.com/mgielda/ecos-colibri-vf61.git + +Preparing an :abbr:`.ecc` file +------------------------------ + +The actual configuration of the eCos system is maintained and modified through :program:`ecosconfig`. +The following commands will prepare a sample :abbr:`.ecc` file for a kernel with default settings. + +.. topic:: Generating the kernel ecc file from scratch + + .. code-block:: bash + + export ECOS_REPOSITORY="{path/to/ecos-colibri-vf61/ecos}/packages" # modify + # Create ecos.ecc file based on Colibri VF61 default template + ecosconfig new col_vf61 default + +You now have a ``ecos.ecc`` file that holds the default eCos configuration for Colibri VF61. +The file can be further edited manually with a text editor and/or :program:`ecosconfig` or graphically using :program:`configtool` (see :ref:`custom-config`), but at this moment it is already enough to compile a sample eCos kernel. + +.. _build-kernel: + +Building the kernel +------------------- + +The eCos kernel is built in two stages: + +* first, a so-called *build tree* is generated from the eCos sources by :program:`ecosconfig`. + The build tree is customized for your build as configured in the :abbr:`.ecc` file used. + It is best to generate the build tree in a separate directory (here ``build-tree``). +* then, the source files are compiled + +A short shell script is proposed to make the compilation process easier: + +.. topic:: Building the eCos kernel + + .. code-block:: bash + + export ECOS_REPOSITORY="{path/to/ecos-colibri-vf61/ecos}/packages" # modify + export PATH="{path/to/toolchain}/bin:$PATH" # modify + + mkdir -p build-tree + rm -rf build-tree/* + cd build-tree + + ecosconfig --config={path/to}/ecos.ecc tree # modify + make + cd .. + +The resulting kernel files can be found in :file:`build-tree/install/lib`. + +Application +----------- + +With a compiled kernel files in the :file:`build-tree/install/lib` directory (see :ref:`build-kernel`), a user space eCos application can be compiled and linked to it. + +A listing for a short sample application (taken from :file:`ecos-colibri-vf61/ecos/examples/hello.c`) is given below. + +.. topic:: hello.c - sample application + + .. code-block:: c + + #include <stdio.h> + + int main(void) + { + printf("Hello, eCos world!\r\n"); + return 0; + } + +You can compile an eCos program with a procedure similar to the following listing (which you can save for reuse, for example as ``make.sh``): + +.. topic:: Building a user space application + + .. code-block:: bash + + export PATH="{path/to/toolchain}/bin:$PATH" # modify + + # Set compiler options + OPT="-Wall -Wpointer-arith -Wstrict-prototypes -Wundef \ + -Wno-write-strings -mthumb -g -O2 -fdata-sections \ + -ffunction-sections -fno-exceptions -nostdlib \ + -mcpu=cortex-m4" + + # Set path to eCos kernel + BTPATH="{path/to/ecos/build-tree}" # modify + + # Do compilation and link your application with kernel + arm-eabi-gcc -g -I./ -g -I${BTPATH}/install/include hello.c \ + -L${BTPATH}/install/lib -Ttarget.ld ${OPT} + + # Use objcopy to generate a binary + arm-eabi-objcopy -O binary a.out hello.bin + |