summaryrefslogtreecommitdiffstats
path: root/user/start
diff options
context:
space:
mode:
Diffstat (limited to 'user/start')
-rw-r--r--user/start/app.rst244
-rw-r--r--user/start/bootstrap.rst55
-rw-r--r--user/start/bsp-build.rst274
-rw-r--r--user/start/bsp-test.rst68
-rw-r--r--user/start/gsoc.rst140
-rw-r--r--user/start/host.rst21
-rw-r--r--user/start/index.rst5
-rw-r--r--user/start/prefixes.rst39
-rw-r--r--user/start/preparation.rst119
-rw-r--r--user/start/rsb-packages.rst184
-rw-r--r--user/start/sources.rst139
-rw-r--r--user/start/tools.rst170
12 files changed, 1113 insertions, 345 deletions
diff --git a/user/start/app.rst b/user/start/app.rst
index fdf6bb7..0599305 100644
--- a/user/start/app.rst
+++ b/user/start/app.rst
@@ -1,11 +1,249 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
-.. Copyright (C) 2019 embedded brains GmbH
-.. Copyright (C) 2019 Sebastian Huber
+.. Copyright (C) 2020 Chris Johns
.. _QuickStartAPP:
Build Your Application
======================
-TODO
+You tested a BSP in the previous section. We built the ``erc32`` BSP
+and it is installed under :file:`$HOME/quick-start/rtems/@rtems-ver-major@`.
+
+We will now create a simple Hello World application with a Git
+repository and using the `Waf <https://waf.io>`_ build system.
+
+The application is be created in :file:`$HOME/quick-start/app/hello`.
+
+In the output in this section the base directory :file:`$HOME/quick-start` was
+replaced by ``$BASE``.
+
+The steps in this section assume you are in the directory
+:file:`$HOME/quick-start/app/hello` after the first step changes to
+it.
+
+Setup the application work space. Create a new Git repository, download
+the Waf build system, and the `RTEMS Waf
+<https://git.rtems.org/rtems_waf.git/tree/README>`_.
+
+Create the application directory and change into it:
+
+.. code-block:: none
+
+ mkdir -p $HOME/quick-start/app/hello
+ cd $HOME/quick-start/app/hello
+
+Download the Waf build system and set it to executable:
+
+.. code-block:: none
+
+ curl https://waf.io/waf-2.0.19 > waf
+ chmod +x waf
+
+Initialise a new Git repository:
+
+.. code-block:: none
+
+ git init
+
+Add RTEMS Waf support as a Git sub-module and initialise it:
+
+.. code-block:: none
+
+ git submodule add git://git.rtems.org/rtems_waf.git rtems_waf
+
+Create the application source files. Three files are created with an
+editor of your choice.
+
+First create a C file that configures RTEMS. Using an editor create a
+file called :file:`init.c` and copy the following configuration
+settings:
+
+.. code-block:: c
+
+ /*
+ * Simple RTEMS configuration
+ */
+
+ #define CONFIGURE_APPLICATION_NEEDS_CLOCK_DRIVER
+ #define CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER
+
+ #define CONFIGURE_UNLIMITED_OBJECTS
+ #define CONFIGURE_UNIFIED_WORK_AREAS
+
+ #define CONFIGURE_RTEMS_INIT_TASKS_TABLE
+
+ #define CONFIGURE_INIT
+
+ #include <rtems/confdefs.h>
+
+Create the Hello World application source file. Using an editor
+create :file:`hello.c` and copy the follow code:
+
+.. code-block:: c
+
+ /*
+ * Hello world example
+ */
+ #include <rtems.h>
+ #include <stdlib.h>
+ #include <stdio.h>
+
+ rtems_task Init(
+ rtems_task_argument ignored
+ )
+ {
+ printf( "\nHello World\n" );
+ exit( 0 );
+ }
+
+Finally create the Waf script. Using an editor create :file:`wscript`
+and copy the Waf script:
+
+.. code-block:: python
+
+ #
+ # Hello world Waf script
+ #
+ from __future__ import print_function
+
+ rtems_version = "6"
+
+ try:
+ import rtems_waf.rtems as rtems
+ except:
+ print('error: no rtems_waf git submodule')
+ import sys
+ sys.exit(1)
+
+ def init(ctx):
+ rtems.init(ctx, version = rtems_version, long_commands = True)
+
+ def bsp_configure(conf, arch_bsp):
+ # Add BSP specific configuration checks
+ pass
+
+ def options(opt):
+ rtems.options(opt)
+
+ def configure(conf):
+ rtems.configure(conf, bsp_configure = bsp_configure)
+
+ def build(bld):
+ rtems.build(bld)
+
+ bld(features = 'c cprogram',
+ target = 'hello.exe',
+ cflags = '-g -O2',
+ source = ['hello.c',
+ 'init.c'])
+
+Configure the application using Waf's ``configure`` command:
+
+.. code-block:: none
+
+ ./waf configure --rtems=$HOME/quick-start/rtems/6 --rtems-bsp=sparc/erc32
+
+The output will be something close to:
+
+.. code-block:: none
+
+ Setting top to : $BASE/app/hello
+ Setting out to : $BASE/app/hello/build
+ RTEMS Version : @rtems-ver-major@
+ Architectures : sparc-rtems@rtems-ver-major@
+ Board Support Package (BSP) : sparc-rtems@rtems-ver-major@-erc32
+ Show commands : no
+ Long commands : no
+ Checking for program 'sparc-rtems@rtems-ver-major@-gcc' : $BASE/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-gcc
+ Checking for program 'sparc-rtems@rtems-ver-major@-g++' : $BASE/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-g++
+ Checking for program 'sparc-rtems@rtems-ver-major@-gcc' : $BASE/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-gcc
+ Checking for program 'sparc-rtems@rtems-ver-major@-ld' : $BASE/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-ld
+ Checking for program 'sparc-rtems@rtems-ver-major@-ar' : $BASE/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-ar
+ Checking for program 'sparc-rtems@rtems-ver-major@-nm' : $BASE/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-nm
+ Checking for program 'sparc-rtems@rtems-ver-major@-objdump' : $BASE/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-objdump
+ Checking for program 'sparc-rtems@rtems-ver-major@-objcopy' : $BASE/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-objcopy
+ Checking for program 'sparc-rtems@rtems-ver-major@-readelf' : $BASE/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-readelf
+ Checking for program 'sparc-rtems6-strip' : $BASE/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-strip
+ Checking for program 'sparc-rtems6-ranlib' : $BASE/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-ranlib
+ Checking for program 'rtems-ld' : $BASE/rtems/@rtems-ver-major@/bin/rtems-ld
+ Checking for program 'rtems-tld' : $BASE/rtems/@rtems-ver-major@/bin/rtems-tld
+ Checking for program 'rtems-syms' : $BASE/rtems/@rtems-ver-major@/bin/rtems-syms
+ Checking for program 'rtems-bin2c' : $BASE/rtems/@rtems-ver-major@/bin/rtems-bin2c
+ Checking for program 'tar' : /usr/bin/tar
+ Checking for program 'gcc, cc' : $BASE/rtems/6/bin/sparc-rtems6-gcc
+ Checking for program 'ar' : $BASE/rtems/6/bin/sparc-rtems6-ar
+ Checking for program 'g++, c++' : $BASE/rtems/6/bin/sparc-rtems6-g++
+ Checking for program 'ar' : $BASE/rtems/6/bin/sparc-rtems6-ar
+ Checking for program 'gas, gcc' : $BASE/rtems/6/bin/sparc-rtems6-gcc
+ Checking for program 'ar' : $BASE/rtems/6/bin/sparc-rtems6-ar
+ Checking for c flags '-MMD' : yes
+ Checking for cxx flags '-MMD' : yes
+ Compiler version (sparc-rtems@rtems-ver-major@-gcc) : 10.2.1 20210309 (RTEMS @rtems-ver-major@, RSB 5e449fb5c2cb6812a238f9f9764fd339cbbf05c2, Newlib d10d0d9)
+ Checking for a valid RTEMS BSP installation : yes
+ Checking for RTEMS_DEBUG : no
+ Checking for RTEMS_MULTIPROCESSING : no
+ Checking for RTEMS_NEWLIB : yes
+ Checking for RTEMS_POSIX_API : no
+ Checking for RTEMS_SMP : no
+ Checking for RTEMS_NETWORKING : no
+ 'configure' finished successfully (1.142s)
+Build the application:
+
+.. code-block:: none
+
+ ./waf
+
+The output will be something close to:
+
+.. code-block:: none
+
+ Waf: Entering directory `$BASE/app/hello/build/sparc-rtems@rtems-ver-major@-erc32'
+ [1/3] Compiling init.c
+ [2/3] Compiling hello.c
+ [3/3] Linking build/sparc-rtems@rtems-ver-major@-erc32/hello.exe
+ Waf: Leaving directory `$BASE/app/hello/build/sparc-rtems@rtems-ver-major@-erc32'
+ 'build-sparc-rtems@rtems-ver-major@-erc32' finished successfully (0.183s)
+
+Run the executable:
+
+.. code-block:: none
+
+ rtems-run --rtems-bsps=erc32-sis build/sparc-rtems@rtems-ver-major@-erc32/hello.exe
+
+The output will be something close to:
+
+.. code-block:: none
+
+ RTEMS Testing - Run, @rtems-ver-mjminrev@
+ Command Line: $BASE/quick-start/rtems/@rtems-ver-major@/bin/rtems-run --rtems-bsps=erc32-sis build/sparc-rtems@rtems-ver-major@-erc32/hello.exe
+ Host: Linux 5.8.0-44-generic #50~20.04.1-Ubuntu SMP Wed Feb 10 21:07:30 UTC 2021 x86_64
+ Python: 3.8.5 (default, Jan 27 2021, 15:41:15) [GCC 9.3.0]
+ Host: Linux-5.8.0-44-generic-x86_64-with-glibc2.29 (Linux 5.8.0-44-generic #50~20.04.1-Ubuntu SMP Wed Feb 10 21:07:30 UTC 2021 x86_64 x86_64)
+
+ SIS - SPARC/RISCV instruction simulator 2.26, copyright Jiri Gaisler 2020
+ Bug-reports to jiri@gaisler.se
+
+ ERC32 emulation enabled
+
+ Loaded build/sparc-rtems@rtems-ver-major@-erc32/hello.exe, entry 0x02000000
+
+ Hello World
+
+ *** FATAL ***
+ fatal source: 5 (RTEMS_FATAL_SOURCE_EXIT)
+ fatal code: 0 (0x00000000)
+ RTEMS version: 6.0.0.586e06ec6222f1cd1f005aa8f4a34a8b33f5d862
+ RTEMS tools: 10.2.1 20210309 (RTEMS @rtems-ver-major@, RSB 5e449fb5c2cb6812a238f9f9764fd339cbbf05c2, Newlib d10d0d9)
+ executing thread ID: 0x08a010001
+ executing thread name: UI1
+ cpu 0 in error mode (tt = 0x101)
+ 158479 0200d500: 91d02000 ta 0x0
+ Run time : 0:00:00.259136
+
+Commit the application to the repository:
+
+.. code-block:: none
+
+ git add init.c hello.c wscript
+ git commit -m "My first RTEMS application."
diff --git a/user/start/bootstrap.rst b/user/start/bootstrap.rst
deleted file mode 100644
index 9fcf79b..0000000
--- a/user/start/bootstrap.rst
+++ /dev/null
@@ -1,55 +0,0 @@
-.. SPDX-License-Identifier: CC-BY-SA-4.0
-
-.. Copyright (C) 2019 embedded brains GmbH
-.. Copyright (C) 2019 Sebastian Huber
-
-.. _QuickStartBootstrap:
-
-Bootstrap the RTEMS Sources
-===========================
-
-You installed the tool suite in your installation prefix and cloned two RTEMS
-repositories in the previous sections. We installed the tool suite in
-:file:`$HOME/quick-start/rtems/5` and cloned the repositories in
-:file:`$HOME/quick-start/src`.
-
-If you use source archives of a released RTEMS version, then you can skip this
-section.
-
-Before you can build a :ref:`Board Support Package (BSP) <BSPs>` for your
-target hardware, you have to bootstrap the build system in the RTEMS sources.
-This is only necessary, if you use a Git repository clone of the RTEMS sources.
-You have to do this after a fresh repository clone and sometimes after build
-system file updates (e.g. after a ``git pull``). If you are not a build
-system expert, then do the bootstrap after each update of build system files.
-This is a bit annoying, but improving the build system is a complex and time
-consuming undertaking. Feel free to help the RTEMS Project to improve it. For
-the bootstrap it is important that the right version of Autotools
-(:file:`autoconf` and :file:`automake`) are in your ``$PATH``. The right
-version of Autotools is shipped with the RTEMS tool suite you already
-installed.
-
-.. code-block:: none
-
- cd $HOME/quick-start/src/rtems
- export PATH=$HOME/quick-start/rtems/5/bin:"$PATH"
- ./bootstrap -c
- $HOME/quick-start/src/rsb/source-builder/sb-bootstrap
-
-These commands should output something like this (omitted lines are denoted by
-...):
-
-.. code-block:: none
-
- removing automake generated Makefile.in files
- removing configure files
- removing aclocal.m4 files
- $ $HOME/quick-start/src/rsb/source-builder/sb-bootstrap
- RTEMS Source Builder - RTEMS Bootstrap, 5 (f07504d27192)
- 1/120: autoreconf: configure.ac
- 2/120: autoreconf: c/configure.ac
- 3/120: autoreconf: c/src/configure.ac
- 4/120: autoreconf: c/src/lib/libbsp/arm/configure.ac
- ...
- 120/120: autoreconf: testsuites/tmtests/configure.ac
- Bootstrap time: 0:00:48.744222
diff --git a/user/start/bsp-build.rst b/user/start/bsp-build.rst
index 3b9eb15..962cd43 100644
--- a/user/start/bsp-build.rst
+++ b/user/start/bsp-build.rst
@@ -1,6 +1,6 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
-.. Copyright (C) 2019 embedded brains GmbH
+.. Copyright (C) 2019 embedded brains GmbH & Co. KG
.. Copyright (C) 2019 Sebastian Huber
.. _QuickStartBSPBuild:
@@ -8,111 +8,200 @@
Build a Board Support Package (BSP)
===================================
-You installed the tool suite in your installation prefix, cloned two RTEMS
-repositories and bootstrapped the RTEMS sources in the previous sections. We
-installed the tool suite in :file:`$HOME/quick-start/rtems/5` and cloned the
-repositories in :file:`$HOME/quick-start/src`. We also bootstrapped the RTEMS
-sources.
+You installed the tool suite in your installation prefix, made ready the source
+for two RTEMS source packages and if you are using a Git clone bootstrapped the
+RTEMS sources in the previous sections. We installed the tool suite in
+:file:`$HOME/quick-start/rtems/6` and unpacked the source in
+:file:`$HOME/quick-start/src`.
You are now able to build :ref:`Board Support Packages (BSPs) <BSPs>` for all
-architectures where you have an RTEMS tool suite installed. To build
-applications on top of RTEMS, you have to configure, build and install a BSP
-for your target hardware. To select a proper BSP for your target hardware
-consult the :ref:`BSPs <BSPs>` chapter. We select the `erc32` BSP.
+architectures you have an installed RTEMS tool suite. To build applications on
+top of RTEMS, you have to build and install a BSP for your target hardware. To
+select a proper BSP for your target hardware consult the :ref:`BSPs <BSPs>`
+chapter. We select the `erc32` BSP. The ``erc32`` BSP uses approximately 2.3G
+bytes of disk space when the testsuite is built and 44M bytes of space when
+installed.
-We configure, build and install the BSP in four steps. The first step is to
-create a build directory. It must be separate from the RTEMS source directory.
-We use :file:`$HOME/quick-start/build/b-erc32`.
+We will first show how to build the BSP using the RSB and then we will show how
+to build the same BSP `manually <QuickStartBSPBuild_Manual>`_. You only need to
+use one of the listed methods to build the BSP.
+
+In the output in this section the base directory :file:`$HOME/quick-start` was
+replaced by ``$BASE``.
+
+.. _QuickStartBSPBuild_RSB:
+
+RSB BSP Build
+-------------
+
+The RSB build of RTEMS does not use the RTEMS source we made ready. It uses the
+RSB source you downloaded in a previous section. If you are using a release RSB
+source archive the BSP built is the released kernel image. If you are using a
+Git clone of the RSB the BSP will be version referenced in the RSB clone.
+
+To build the BSP with all the tests run this command:
.. code-block:: none
- mkdir -p $HOME/quick-start/build/b-erc32
+ cd $HOME/quick-start/src/rsb/rtems
+ ../source-builder/sb-set-builder --prefix=$HOME/quick-start/rtems/5 \
+ --target=sparc-rtems@rtems-ver-major@ --with-rtems-bsp=sparc/erc32 --with-rtems-tests=yes @rtems-ver-major@/rtems-kernel
-The second step is to configure the BSP. There are various configuration
-options available. Some configuration options are BSP-specific. Prepend the
-RTEMS tool suite binary directory to your ``$PATH`` throughout the remaining
-steps.
+This command should output something like:
.. code-block:: none
- cd $HOME/quick-start/build/b-erc32
- export PATH=$HOME/quick-start/rtems/5/bin:"$PATH"
- $HOME/quick-start/src/rtems/configure \
- --prefix=$HOME/quick-start/rtems/5 \
- --enable-maintainer-mode \
- --target=sparc-rtems5 \
- --enable-rtemsbsp=erc32 \
- --enable-tests
+ RTEMS Source Builder - Set Builder, @rtems-ver-majminver@
+ Build Set: @rtems-ver-major@/rtems-kernel
+ config: tools/rtems-kernel-@rtems-ver-major@.cfg
+ package: sparc-rtems@rtems-ver-major@-kernel-erc32-1
+ building: sparc-rtems@rtems-ver-major@-kernel-erc32-1
+ sizes: sparc-rtems@rtems-ver-major@-kernel-erc32-1: 2.279GB (installed: 44.612MB)
+ cleaning: sparc-rtems@rtems-ver-major@-kernel-erc32-1
+ reporting: tools/rtems-kernel-@rtems-ver-major@.cfg -> sparc-rtems@rtems-ver-major@-kernel-erc32-1.txt
+ reporting: tools/rtems-kernel-@rtems-ver-major@.cfg -> sparc-rtems@rtems-ver-major@-kernel-erc32-1.xml
+ installing: sparc-rtems@rtems-ver-major@-kernel-erc32-1 -> $BASE/
+ cleaning: sparc-rtems@rtems-ver-major@-kernel-erc32-1
+ Build Set: Time 0:03:09.896961
+
+The RSB BSP build can be customised with following RSB command line options:
+
+``--with-rtems-tests``:
+ Build the test suite. If ``yes`` is provided all tests in the testsuite are
+ build. If ``no`` is provided no tests are built and if ``samples`` is
+ provided only the sample executables are built, e.g.
+ ``--with-rtems-tests=yes``. The test executables are install under the BSP
+ in the :file:`tests` directory and you can execute them with the
+ :ref:`tester and run command <rtems-tester-command>`.
+
+``--with-rtems-smp``:
+ Build with SMP support. The BSP has to have SMP support or this option will
+ fail with an error.
+
+``--with-rtems-legacy-network``:
+ Build the legacy network software. We recommend you use the current network
+ support in the RTEMS BSP Library (libbsd) unless you need to maintain a
+ legacy product. Do not use the legacy networking software for new
+ developments.
+
+``--with-rtems-bspopts``:
+ Build the BSP with BSP specific options. This is an advanced option. Please
+ refer to the BSP specific details in the :ref:`Board Support Packages
+ (BSPs)` of this manual or the BSP source code in the RTEMS source
+ directory. To supply a list of options quote then list with ``"``, e.g.
+ ``--with-rtems-bspopts="BSP_POWER_DOWN_AT_FATAL_HALT=1"``
+
+If you have built a BSP with the RSB, you can move on to
+:ref:`QuickStartBSPTest`.
+
+.. _QuickStartBSPBuild_Manual:
+
+Manual BSP Build
+----------------
+
+We manually build the BSP in four steps. The first step is to set your path.
+Prepend the RTEMS tool suite binary directory to your ``$PATH`` throughout the
+remaining steps. Run the command:
-This command should output something like this (omitted lines are denoted by
-...):
+.. code-block:: none
+
+ export PATH=$HOME/quick-start/rtems/@rtems-ver-major@/bin:"$PATH"
+
+Check your installed tools can be found by running:
.. code-block:: none
- checking for gmake... gmake
- checking for RTEMS Version... 5.0.0
- checking build system type... x86_64-unknown-freebsd12.0
- checking host system type... x86_64-unknown-freebsd12.0
- checking target system type... sparc-unknown-rtems5
- ...
- config.status: creating Makefile
+ command -v sparc-rtems@rtems-ver-major@-gcc && echo "found" || echo "not found"
+
+The output should be:
+
+.. code-block:: none
- target architecture: sparc.
- available BSPs: erc32.
- 'gmake all' will build the following BSPs: erc32.
- other BSPs can be built with 'gmake RTEMS_BSP="bsp1 bsp2 ..."'
+ found
- config.status: creating Makefile
+If ``not found`` is printed the tools are not correctly installed or the path
+has not been correctly set. Check the contents of the path
+:file:`$HOME/quick-start/rtems/@rtems-ver-major@/bin` manually and if
+:file:`sparc-rtems@rtems-ver-major@-gcc` is present the path is wrong. If the
+file cannot be found return to :ref:`QuickStartTools` and install the tools
+again.
+
+The second step is to configure the BSP. There are various BSP build
+configuration options available. Some options are BSP-specific. Each section
+in the INI-style configuration file ``config.ini`` instructs the build system to
+build a particular BSP variant (`sparc/erc32` in our case). We enable the build
+of the tests with the ``BUILD_TESTS = True`` option and use default values for
+everything else. For detailed information about the BSP build system, see
+:ref:`BSPBuildSystem`.
+
+.. code-block:: none
+
+ cd $HOME/quick-start/src/rtems
+ echo "[sparc/erc32]" > config.ini
+ echo "BUILD_TESTS = True" >> config.ini
+ ./waf configure --prefix=$HOME/quick-start/rtems/@rtems-ver-major@
+
+The first invocation of ``./waf`` needs a bit of time (e.g. 10 seconds) since an
+internal cache file is populated. This command should output something like
+this. In this output the base directory :file:`$HOME/quick-start` was replaced
+by ``$BASE``.
+
+.. code-block:: none
+
+ Setting top to : $BASE/quick-start/src/rtems
+ Setting out to : $BASE/quick-start/src/rtems/build
+ Configure board support package (BSP) : sparc/erc32
+ Checking for program 'sparc-rtems@rtems-ver-major@-gcc' : $BASE/quick-start/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-gcc
+ Checking for program 'sparc-rtems@rtems-ver-major@-g++' : $BASE/quick-start/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-g++
+ Checking for program 'sparc-rtems@rtems-ver-major@-ar' : $BASE/quick-start/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-ar
+ Checking for program 'sparc-rtems@rtems-ver-major@-ld' : $BASE/quick-start/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-ld
+ Checking for program 'ar' : $BASE/quick-start/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-ar
+ Checking for program 'g++, c++' : $BASE/quick-start/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-g++
+ Checking for program 'ar' : $BASE/quick-start/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-ar
+ Checking for program 'gas, gcc' : $BASE/quick-start/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-gcc
+ Checking for program 'ar' : $BASE/quick-start/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-ar
+ Checking for program 'gcc, cc' : $BASE/quick-start/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-gcc
+ Checking for program 'ar' : $BASE/quick-start/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-ar
+ Checking for asm flags '-MMD' : yes
+ Checking for c flags '-MMD' : yes
+ Checking for cxx flags '-MMD' : yes
+ Checking for program 'rtems-bin2c' : $BASE/quick-start/rtems/@rtems-ver-major@/bin/rtems-bin2c
+ Checking for program 'gzip' : /usr/bin/gzip
+ Checking for program 'rtems-ld' : $BASE/quick-start/rtems/@rtems-ver-major@/bin/rtems-ld
+ Checking for program 'rtems-syms' : $BASE/quick-start/rtems/@rtems-ver-major@/bin/rtems-syms
+ Checking for program 'xz' : $BASE/anaconda3/bin/xz
+ 'configure' finished successfully (0.414s)
Building the BSP is the third step.
.. code-block:: none
- cd $HOME/quick-start/build/b-erc32
- make
+ cd $HOME/quick-start/src/rtems
+ ./waf
This command should output something like this (omitted lines are denoted by
-...). In this output the base directory :file:`$HOME/quick-start` was replaced
-by ``$BASE``.
+...).
.. code-block:: none
- Configuring RTEMS_BSP=erc32
- checking for gmake... gmake
- checking build system type... x86_64-unknown-freebsd12.0
- checking host system type... sparc-unknown-rtems5
- checking rtems target cpu... sparc
- checking for a BSD-compatible install... /usr/bin/install -c
- checking whether build environment is sane... yes
- checking for sparc-rtems5-strip... sparc-rtems5-strip
- checking for a thread-safe mkdir -p... $BASE/src/rtems/c/src/../../install-sh -c -d
- checking for gawk... no
- checking for mawk... no
- checking for nawk... nawk
- checking whether gmake sets $(MAKE)... yes
- checking whether to enable maintainer-specific portions of Makefiles... yes
- checking for RTEMS_BSP... erc32
- checking whether CPU supports libposix... yes
- configure: setting up make/custom
- configure: creating make/erc32.cache
- gmake[3]: Entering directory '$BASE/build/b-erc32/sparc-rtems5/c/erc32'
- ...
- sparc-rtems5-gcc -mcpu=cypress -O2 -g -ffunction-sections -fdata-sections -Wall -Wmissing-prototypes -Wimplicit-function-declaration -Wstrict-prototypes -Wnested-externs -B./../../lib/libbsp/sparc/erc32 -B$BASE/src/rtems/bsps/sparc/erc32/start -specs bsp_specs -qrtems -L./../../cpukit -L$BASE/src/rtems/bsps/sparc/shared/start -Wl,--wrap=printf -Wl,--wrap=puts -Wl,--wrap=putchar -Wl,--gc-sections -o spwkspace.exe spwkspace/spwkspace-init.o ./../../lib/libbsp/sparc/erc32/librtemsbsp.a ./../../cpukit/librtemscpu.a
- gmake[5]: Leaving directory '$BASE/build/b-erc32/sparc-rtems5/c/erc32/testsuites/sptests'
- gmake[4]: Leaving directory '$BASE/build/b-erc32/sparc-rtems5/c/erc32/testsuites'
- gmake[3]: Leaving directory '$BASE/build/b-erc32/sparc-rtems5/c/erc32'
- gmake[2]: Leaving directory '$BASE/build/b-erc32/sparc-rtems5/c/erc32'
- gmake[1]: Leaving directory '$BASE/build/b-erc32/sparc-rtems5/c'
- gmake[1]: Entering directory '$BASE/build/b-erc32'
- gmake[1]: Nothing to be done for 'all-am'.
- gmake[1]: Leaving directory '$BASE/build/b-erc32'
+ Waf: Entering directory `$BASE/quick-start/src/rtems/build'
+ Waf: Leaving directory `$BASE/quick-start/src/rtems/build'
+ 'build' finished successfully (0.085s)
+ Waf: Entering directory `$BASE/quick-start/src/rtems/build/sparc/erc32'
+ [ 1/4093] Compiling bsps/shared/dev/serial/mc68681_reg2.c
+ [ 2/4093] Compiling bsps/shared/dev/rtc/mc146818a_ioreg.c
+ [ 3/4093] Compiling bsps/shared/dev/flash/am29lv160.c
+ ...
+ [4093/4093] Processing link: build/sparc/erc32/testsuites/libtests/dl01/dl01-tar.o build/sparc/erc32/testsuites/libtests/dl01/init.o build/sparc/erc32/testsuites/libtests/dl01/dl-load.o build/sparc/erc32/testsuites/libtests/dl01/dl01-sym.o -> build/sparc/erc32/testsuites/libtests/dl01.exe
+ Waf: Leaving directory `$BASE/quick-start/src/rtems/build/sparc/erc32'
+ 'build_sparc/erc32' finished successfully (2m14.111s)
The last step is to install the BSP.
.. code-block:: none
- cd $HOME/quick-start/build/b-erc32
- make install
+ cd $HOME/quick-start/src/rtems
+ ./waf install
This command should output something like this (omitted lines are denoted by
...). In this output the base directory :file:`$HOME/quick-start` was replaced
@@ -120,27 +209,16 @@ by ``$BASE``.
.. code-block:: none
- Making install in sparc-rtems5/c
- gmake[1]: Entering directory '$BASE/build/b-erc32/sparc-rtems5/c'
- Making install in .
- gmake[2]: Entering directory '$BASE/build/b-erc32/sparc-rtems5/c'
- gmake[3]: Entering directory '$BASE/build/b-erc32/sparc-rtems5/c'
- gmake[3]: Nothing to be done for 'install-exec-am'.
- gmake[3]: Nothing to be done for 'install-data-am'.
- gmake[3]: Leaving directory '$BASE/build/b-erc32/sparc-rtems5/c'
- gmake[2]: Leaving directory '$BASE/build/b-erc32/sparc-rtems5/c'
- Making install in erc32
- gmake[2]: Entering directory '$BASE/build/b-erc32/sparc-rtems5/c/erc32'
- gmake[3]: Entering directory '$BASE/build/b-erc32/sparc-rtems5/c/erc32'
- Making install-am in .
- Making install-am in cpukit
- gmake[4]: Entering directory '$BASE/build/b-erc32/sparc-rtems5/c/erc32/cpukit'
- gmake[5]: Entering directory '$BASE/build/b-erc32/sparc-rtems5/c/erc32/cpukit'
- gmake[5]: Nothing to be done for 'install-exec-am'.
- $BASE/src/rtems/c/src/../../cpukit/../install-sh -c -d '$BASE/rtems/5/sparc-rtems5/erc32/lib/include'
+ Waf: Entering directory `$BASE/quick-start/src/rtems/build'
+ Waf: Leaving directory `$BASE/quick-start/src/rtems/build'
+ 'install' finished successfully (0.081s)
+ Waf: Entering directory `$BASE/quick-start/src/rtems/build/sparc/erc32'
+ + install $BASE/quick-start/rtems/@rtems-ver-major@/sparc-rtems@rtems-ver-major@/erc32/lib/include/libchip/am29lv16.h (from bsps/include/libchip/am29lv1.h)
+ + install $BASE/quick-start/rtems/@rtems-ver-major@/sparc-rtems@rtems-ver-major@/erc32/lib/include/libchip/mc146818a.h (from bsps/include/libchip/mc146818a.h)
+ + install $BASE/quick-start/rtems/@rtems-ver-major@/sparc-rtems@rtems-ver-major@/erc32/lib/include/libchip/mc68681.h (from bsps/include/libchip/mc68681.h))
...
- $BASE/src/rtems/make/Templates/Makefile.lib '$BASE/rtems/5/share/rtems5/make/Templates'
- $BASE/src/rtems/./install-sh -c -d '$BASE/rtems/5/make/custom'
- /usr/bin/install -c -m 644 $BASE/src/rtems/make/custom/default.cfg '$BASE/rtems/5/make/custom'
- gmake[2]: Leaving directory '$BASE/build/b-erc32'
- gmake[1]: Leaving directory '$BASE/build/b-erc32'
+ + install $BASE/quick-start/rtems/@rtems-ver-major@/sparc-rtems@rtems-ver-major@/erc32/lib/include/rtems/score/watchdogticks.h (from cpukit/include/rtems/score/watchdogticks.h)
+ + install $BASE/quick-start/rtems/@rtems-ver-major@/sparc-rtems@rtems-ver-major@/erc32/lib/include/rtems/score/wkspace.h (from cpukit/include/rtems/score/wkspace.h)
+ + install $BASE/quick-start/rtems/@rtems-ver-major@/sparc-rtems@rtems-ver-major@/erc32/lib/include/rtems/score/wkspacedata.h (from cpukit/include/rtems/score/wkspacedata.h)
+ Waf: Leaving directory `$BASE/quick-start/src/rtems/build/sparc/erc32'
+ 'install_sparc/erc32' finished successfully (1.834s))
diff --git a/user/start/bsp-test.rst b/user/start/bsp-test.rst
index aefeeb9..a354663 100644
--- a/user/start/bsp-test.rst
+++ b/user/start/bsp-test.rst
@@ -1,6 +1,6 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
-.. Copyright (C) 2019 embedded brains GmbH
+.. Copyright (C) 2019 embedded brains GmbH & Co. KG
.. Copyright (C) 2019 Sebastian Huber
.. _QuickStartBSPTest:
@@ -8,20 +8,20 @@
Test a Board Support Package (BSP)
==================================
-You built a BSP with tests in the previous section. We built the ``erc32`` BSP
-in :file:`$HOME/quick-start/build/b-erc32`.
+You built a BSP with tests in the previous section. We built the
+``sparc/erc32`` BSP in :file:`$HOME/quick-start/src/rtems`.
You should run the RTEMS test suite on your target hardware. The RTEMS Project
provides some support to do this, see the :ref:`Testing <Testing>` chapter for
the details.
-On the ``erc32`` BSP we selected for this quick start chapter this is easy.
-Just run this command:
+On the ``sparc/erc32`` BSP we selected for this quick start chapter this is
+easy. Just run this command:
.. code-block:: none
- cd $HOME/quick-start/build/b-erc32
- rtems-test --rtems-bsp=erc32-sis --rtems-tools=$HOME/quick-start/rtems/5 .
+ cd $HOME/quick-start/src/rtems
+ rtems-test --rtems-bsp=erc32-sis build/sparc/erc32
This command should output something like this (omitted lines are denoted by
...). In this output the base directory :file:`$HOME/quick-start` was replaced
@@ -29,38 +29,44 @@ by ``$BASE``.
.. code-block:: none
- RTEMS Testing - Tester, 5.0.not_released
- Command Line: $BASE/rtems/5/bin/rtems-test --rtems-bsp=erc32-sis --rtems-tools=$BASE/rtems/5 .
- Python: 2.7.15 (default, Jan 10 2019, 01:14:47) [GCC 4.2.1 Compatible FreeBSD Clang 6.0.1 (tags/RELEASE_601/final 335540)]
- Host: FreeBSD-12.0-RELEASE-p2-amd64-64bit-ELF (FreeBSD Build_FreeBSD12 12.0-RELEASE-p2 FreeBSD 12.0-RELEASE-p2 GENERIC amd64 amd64)
- [ 1/589] p:0 f:0 u:0 e:0 I:0 B:0 t:0 i:0 W:0 | sparc/erc32: dhrystone.exe
+ RTEMS Testing - Tester, 5.1.0
+ Command Line: $BASE/rtems/5/bin/rtems-test --rtems-bsp=erc32-sis build/sparc/erc32
+ Host: Linux 5.8.0-44-generic #50~20.04.1-Ubuntu SMP Wed Feb 10 21:07:30 UTC 2021 x86_64
+ Python: 3.8.5 (default, Jan 27 2021, 15:41:15) [GCC 9.3.0]
+ Host: Linux-5.8.0-44-generic-x86_64-with-glibc2.29 (Linux 5.8.0-44-generic #50~20.04.1-Ubuntu SMP Wed Feb 10 21:07:30 UTC 2021 x86_64 x86_64)
+ [ 1/570] p:0 f:0 u:0 e:0 I:0 B:0 t:0 L:0 i:0 W:0 | sparc/erc32: dhrystone.exe
...
- [589/589] p:574 f:0 u:5 e:0 I:0 B:3 t:0 i:0 W:0 | sparc/erc32: tmtimer01.exe
+ [570/570] p:554 f:2 u:6 e:1 I:0 B:3 t:0 L:0 i:0 W:0 | sparc/erc32: ts-validation-1.exe
- Passed: 580
- Failed: 0
- User Input: 5
- Expected Fail: 0
+ Passed: 558
+ Failed: 2
+ User Input: 6
+ Expected Fail: 1
Indeterminate: 0
Benchmark: 3
- Timeout: 1
+ Timeout: 0
+ Test too long: 0
Invalid: 0
Wrong Version: 0
Wrong Build: 0
Wrong Tools: 0
------------------
- Total: 589
+ Total: 570
+ Failures:
+ dl06.exe
+ minimum.exe
User Input:
- monitor.exe
- termios.exe
- top.exe
- fileio.exe
- capture.exe
+ dl10.exe
+ monitor.exe
+ termios.exe
+ top.exe
+ capture.exe
+ fileio.exe
+ Expected Fail:
+ psxfenv01.exe
Benchmark:
- whetstone.exe
- linpack.exe
- dhrystone.exe
- Timeouts:
- pppd.exe
- Average test time: 0:00:00.437773
- Testing time : 0:04:17.848557
+ dhrystone.exe
+ linpack.exe
+ whetstone.exe
+ Average test time: 0:00:00.371256
+ Testing time : 0:03:31.616055
diff --git a/user/start/gsoc.rst b/user/start/gsoc.rst
new file mode 100644
index 0000000..64b15fa
--- /dev/null
+++ b/user/start/gsoc.rst
@@ -0,0 +1,140 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2020 Niteesh Babu <niteesh.gs@gmail.com>
+
+.. _QuickStartGSoC:
+
+GSoC Getting Started
+====================
+
+The goal of this page is to help new users, especially students get RTEMS
+compiled and running so they can start with the real work.
+
+Please join the :r:list:`users` and :r:list:`devel` and ask
+questions. Help correct any deficiencies in the code or documentation you spot,
+including those on the wiki. The ultimate goal of GSoC is to help you become
+part of the open source community.
+
+This section will help you to quickly setup a development environment without
+delving into the details. For more information you can go through the other
+subsections under :ref:`Quick Start <QuickStart>` chapter or ask on the
+:r:list:`devel`.
+
+We recommend new student developers use the current development (unreleased)
+version. The :ref:`Quick Start Preparation <QuickStartPreparation>` should be
+consulted for guidance. Some examples shown may use released versions,
+which may not be recommended for your purposes. If you are unsure, feel free to
+inquire on the :r:list:`devel`.
+
+You will be best served by using a GNU/Linux environment, which could be in a
+virtual machine, for example that uses `Virtualbox <https://www.virtualbox.org/>`_
+and should run on most modern desktop systems. You should also be able to work
+with a MacOS or Windows system, but might encounter more difficulty than a *nix
+environment.
+
+Setting up a development environment consists of the following steps.
+
+1) Installing dependencies for your host operating system.
+2) Choosing an installation prefix.
+3) Downloading the source code.
+4) Installing the tool suite.
+5) Building the Board Support Package (BSP).
+6) Testing the Board Support Package (BSP).
+
+Installing Dependencies
+-----------------------
+
+You need tools for your host’s operating system to build the RTEMS tool suite
+from source. Please have a look at the :ref:`host-computer` chapter for the
+instructions to install the tools for your OS.
+
+Choosing an installation prefix
+-------------------------------
+
+The term ``prefix`` refers to the path on your computer where the software is to
+be installed.
+You can refer to the :ref:`Prefix <QuickStartPrefixes>` section for details on
+choosing an installation prefix.
+
+Downloading the Sources
+-----------------------
+
+We will be using Git to clone the sources for RTEMS and RSB. This is the
+preferred way if you are planning to make contributions to the RTEMS project.
+
+Please refer to the :ref:`QuickStartSources_Git` section for instructions on
+obtaining sources using Git.
+
+Installing the Tool Suite
+-------------------------
+
+The Tools suite is the collection of tools required to build the BSP. This
+includes the compiler, debugger, assembler and other tools. These tools are
+architecture-specific. We will be installing the SPARC tool suite since we are
+building a SPARC based BSP.
+
+Please refer to the :ref:`QuickStartTools` section for instructions on
+building and installing the tool suite. Remember to use the current version
+associated with the RTEMS development head, see
+:ref:`QuickStartPreparation_Version`.
+
+Building the Board Support Package
+----------------------------------
+
+There are two ways of building a BSP. We could either ask RSB to build the BSP
+or manually build it. In this section will we be building it manually.
+Please refer the :ref:`QuickStartBSPBuild_Manual` section for the
+instructions.
+
+Testing the Board Support Package
+---------------------------------
+
+Testing is an essential part of RTEMS development process. The main reason for
+choosing the SPARC erc32 BSP is that, it has very good simulator support. This
+will allow you to test your changes without the need for SPARC hardware.
+
+Please refer to :ref:`QuickStartBSPTest` for instructions on testing the BSP.
+
+Prove You Can Work On RTEMS
+---------------------------
+
+This section is only for students interested in Google Summer of Code.
+
+You have to finish the following task to prove that you can work on RTEMS.
+
+Modify the hello world example to include a new different print statement.
+Something like "Hello from The Dark Side!". Then send us enough to prove to us
+that you did this. We want to know you can work with RTEMS.
+
+Create a patch of your changes and send it to :r:list:`devel` along with the
+screenshot of the output.
+
+If you followed this guide, this hello world modification will likely need to be
+made in ``$HOME/quick-start/src/rtems/testsuites/samples/hello/init.c``.
+To test your changes, you have to build the BSP again. This could be done by
+running `make` in the BSP build directory.
+
+.. code-block:: none
+
+ cd $HOME/quick-start/src/rtems
+ ./waf
+
+If you are happy with your changes you can commit the changes and send the patch
+to :r:list:`devel`.
+
+Creating and Sending Patches
+----------------------------
+
+Before sending patches, make sure that the changes you have made conforms to
+RTEMS coding standards.
+You can refer to :ref:`Contributing` section for instruction on creating and
+sending patches.
+
+Here are a few pointers to keep in mind while creating the patches.
+
+* Make sure not to commit changes in the master branch. This is to avoid merge
+ conflicts when you are pulling the latest changes from the remote branch.
+* Avoid trailing whitespace errors.
+* The author name of the patch is your full name.
+* The author email of the patch is your valid email address.
+* Ensure that your patches build before sending them for review.
diff --git a/user/start/host.rst b/user/start/host.rst
deleted file mode 100644
index f891f5d..0000000
--- a/user/start/host.rst
+++ /dev/null
@@ -1,21 +0,0 @@
-.. SPDX-License-Identifier: CC-BY-SA-4.0
-
-.. Copyright (C) 2019 embedded brains GmbH
-.. Copyright (C) 2019 Sebastian Huber
-
-.. _QuickStartHost:
-
-Prepare Your Host Computer
-==========================
-
-The *host computer* is a computer you use to develop applications. It runs all
-your tools, editors, documentation viewers, etc. To get started with RTEMS
-development you need tools from your host's operating system to build the RTEMS
-tool suite from source. This is not a one-click installation process, but
-there are :ref:`good reasons <WhyBuildFromSource>` to build everything from
-source. You need a native C, C++ and Python development environment. Please
-make sure that you can build native C/C++ applications on your host computer.
-You must be able to build native Python C modules. Usually, you have to
-install a Python development package for this. Please have a look at the
-:ref:`Host Computer <host-computer>` chapter for the gory details. In
-particular :ref:`Microsoft Windows <microsoft-windows>` user should do this.
diff --git a/user/start/index.rst b/user/start/index.rst
index d6333f3..17c34e1 100644
--- a/user/start/index.rst
+++ b/user/start/index.rst
@@ -14,11 +14,12 @@ applications on top of RTEMS.
.. toctree::
- host
+ preparation
prefixes
sources
tools
- bootstrap
bsp-build
bsp-test
app
+ rsb-packages
+ gsoc
diff --git a/user/start/prefixes.rst b/user/start/prefixes.rst
index 9727503..aee7440 100644
--- a/user/start/prefixes.rst
+++ b/user/start/prefixes.rst
@@ -1,6 +1,6 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
-.. Copyright (C) 2019 embedded brains GmbH
+.. Copyright (C) 2019 embedded brains GmbH & Co. KG
.. Copyright (C) 2019 Sebastian Huber
.. Copyright (C) 2016 Chris Johns <chrisj@rtems.org>
@@ -21,32 +21,39 @@ path. Packages for your host computer typically use a default prefix of
:file:`/usr/local` on FreeBSD and Linux.
You have to select a prefix for your installation. You will build and install
-the RTEMS tool suite, an RTEMS kernel for a BSP and you may build and install
-third party libraries. You can build them all as a stack with a single prefix
-or you can
+the RTEMS tool suite, an RTEMS kernel for a BSP, and you may build and install
+third party libraries. You can build all the parts as a stack with a single
+prefix or you can separate various parts by providing different prefixes to
+each part as it is built. Using separate prefixes is for experienced RTEMS
+users.
-The RTEMS tool suite consists of a cross tool chain (Binutils, GCC, GDB,
-Newlib, etc.) for your target architecture and :ref:`other tools <HostTools>`
-provided by the RTEMS Project. The RTEMS
+Do not select a prefix that is under the top of any of the source trees. The
+prefix collects the install output of the various build steps you take in this
+guide and need to be kept separate from the sources used.
+The RTEMS tool suite consists of a cross tool chain (Binutils, GCC, GDB,
+Newlib, etc.) for your target architecture and :ref:`RTEMS tools <HostTools>`
+provided by the RTEMS Project. The RTEMS Tools are a toolkit that help create
+the RTEMS ecosystem and help support the building of embedded real-time
+applications and systems.
You build and install the tool suite with the :ref:`RTEMS Source Builder (RSB)
<RSB>`. By default, the RSB will start the prefix path with a host operating
-system specific path plus :file:`rtems` plus the RTEMS version, e.g.
-:file:`/opt/rtems/5` on Linux and :file:`/usr/local/rtems/5` on FreeBSD and
-macOS.
+system specific path plus :file:`rtems`, and the RTEMS version, e.g.
+:file:`/opt/rtems/6` on Linux, and :file:`/usr/local/rtems/6` on FreeBSD and
+macOS. Placing the RTEMS version number in the path lets you manage and
+migrate RTEMS versions as they are released.
It is strongly recommended to run the RSB as a *normal user* and not with
*root* privileges (also known as *super user* or *Administrator*). You have to
make sure that your normal user has sufficient privileges to create files and
directories under the prefix. For example, you can create a directory
-:file:`/opt/rtems` and give it to a developer group with read, write and
+:file:`/opt/rtems` and give it to a developer group with read, write, and
execute permissions. Alternatively, you can choose a prefix in your home
-directory, e.g. :file:`$HOME/rtems/5` or with a project-specific component
-:file:`$HOME/project-x/rtems/5`. For more ideas, see the
-:ref:`project sandboxing <ProjectSandboxing>` section. In this quick start
-chapter, we will choose :file:`$HOME/quick-start/rtems/5` for the RTEMS tool
-suite prefix.
+directory, e.g. :file:`$HOME/rtems/6` or with a project-specific component
+:file:`$HOME/project-x/rtems/6`. For more ideas, see the :ref:`project
+sandboxing <ProjectSandboxing>` section. In this quick start chapter, we will
+choose :file:`$HOME/quick-start/rtems/6` for the RTEMS tool suite prefix.
.. warning::
diff --git a/user/start/preparation.rst b/user/start/preparation.rst
new file mode 100644
index 0000000..4bfc214
--- /dev/null
+++ b/user/start/preparation.rst
@@ -0,0 +1,119 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2018 Shashvat Jain
+.. Copyright (C) 2019 embedded brains GmbH & Co. KG
+.. Copyright (C) 2019 Sebastian Huber
+.. Copyright (C) 2020 Chris Johns
+.. Copyright (C) 2020 Gedare Bloom
+
+.. _QuickStartPreparation:
+
+Preparation
+===========
+
+You need to perform some basic preparation to get started with RTEMS
+development. You need tools from your host's operating system to build the
+RTEMS tool suite from source. The RTEMS tools you build are used to build the
+Board Support Package (BSP) libraries for your target hardware from source. The
+BSP libraries contain the RTEMS operating system. This is not a one-click
+installation process, but there are :ref:`good reasons <WhyBuildFromSource>` to
+build everything from source.
+
+During this Quick Start guide you will:
+
+* Select a suitable place to install RTEMS.
+
+* Select if you download all the source code before you start building RTEMS or
+ the source is downloaded on demand as it is needed. If you do not have a
+ reliable internet connection we recommend you download all the source before
+ starting a build.
+
+* Build a tool suite.
+
+* Build and test a BSP.
+
+* Optionally build additional packages.
+
+Alternatively you can build a BSP as a package using the RSB. This is
+covered in :ref:`QuickStartBSPPackages`
+
+Host Computer
+-------------
+
+The *host computer* is a computer you use to develop applications. It runs all
+your tools, editors, documentation viewers, etc. You need a native C, C++, and
+Python development environment. Please make sure you can build native C/C++
+applications on your host computer. You must be able to build native Python C
+modules as some RTEMS tools contain these modules. Usually, you have to
+install a Python development package for this. The Python scripts of the RTEMS
+Project expect on POSIX systems that a ``python`` command is available [1]_.
+Please have a look at the :ref:`Host Computer <host-computer>` chapter for the
+gory details. In particular :ref:`Microsoft Windows <microsoft-windows>` users
+should do this.
+
+Selecting a BSP
+---------------
+
+If you are new to RTEMS and you are looking to try RTEMS then the best suited
+Board Support Package (BSP) is the :ref:`SPARC ERC32 <BSP_sparc_erc32>`
+(``erc32``). The SPARC ERC32 BSP has a robust simulator that runs the example
+and test executables on your host computer. This Quick Start guide will build
+the ``erc32`` BSP and run RTEMS tests executables in the simulator. The ERC32
+BSP is a SPARC architecture BSP so the tool suite name is ``sparc-rtems5``.
+
+If you are looking for a hardware target to run RTEMS on we recommend the
+:ref:`BeagleBone Black <BSP_arm_beagleboneblack>` (``beagleboneblack``)
+BSP. The BeagleBone Black support includes the RTEMS BSD Library (``libbsd``)
+and networking. The BeagleBone Black BSP is an ARM architecture BSP so the tool
+suite name is ``arm-rtems5``.
+
+.. _QuickStartPreparation_Version:
+
+Selecting a Version of RTEMS
+----------------------------
+
+In the examples of this manual we will often refer to a specific version of
+RTEMS, which will usually be the version that accompanied the publication of
+this documentation manual. That may not be the appropriate version for you to
+use, for example, it may be too old (or too new) depending on what you are
+trying to do. If you're not sure what version to use, we generally recommend
+using the most recent release or the development head (master), and you may
+want to consult with the same version of the documentation. We hope that newer
+is better.
+
+An RTEMS *release* involves the creation of a single downloadable file,
+normally a compressed tarball, that packages the source of all the repositories
+in a state consistent with the time the release is created.
+A release branch is a git branch pushed to the repositories named with the
+numeric identifier of the branch.
+A release branch release is a git tag on a release branch with
+the tags pushed to the repositories.
+
+Numbering for RTEMS versions beginning with RTEMS 5 uses a format as follows.
+The master branch has the version **N.0.0** with N being the next major release
+number. The first release of this series has the version number **N.1.0.** and
+there is exactly one commit with this version number in the corresponding
+repository. The first bugfix release (minor release) of this series will have
+the version number **N.2.0**. The release branch will have the version
+number **N.M.1** with **M** being the last minor release of this series.
+
+For example:
++ 5.0.0 is the version number of the development master for the 5 series.
++ 5.1.0 is the first release of the 5 series.
++ 5.1.1 is the version number of the 5 series release branch right after
+ the 5.1.0 release until 5.2.0 is released.
++ 5.2.0 is the first bugfix release of the 5 series
++ 5.2.1 is the version number of the 5 series release branch right after
+ the 5.2.0 release until 5.3.0 is released.
++ 6.0.0 is the version number of the development master for the 6 series.
+
+RTEMS development tools use **N** as the version number and are expected to
+work with all releases and the release branch of the N series.
+So to build tools for compiling RTEMS version number 5.1.0 for SPARC use
+``sparc-rtems5``. Despite the number not increasing, the tools may change
+within a release branch, for example the tools packaged with 5.1.1 still use
+the ``sparc-rtems5`` moniker, but are likely not the same as the tools used
+in version 5.1.0. This tool mismatch can be a source of confusion. Be sure to
+use the toolchain that matches your release.
+
+.. [1] The Python scripts use a shebang of ``#!/usr/bin/env python``.
diff --git a/user/start/rsb-packages.rst b/user/start/rsb-packages.rst
new file mode 100644
index 0000000..3119318
--- /dev/null
+++ b/user/start/rsb-packages.rst
@@ -0,0 +1,184 @@
+.. SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. Copyright (C) 2020 Contemporary Software
+.. Copyright (C) 2020 Chris Johns
+
+.. _QuickStartBSPPackages:
+
+Build an RSB Package
+====================
+
+This section describes how to build an RTEMS package using the RSB. Before we
+start to build a package with the RSB you need to complete these steps:
+
+- :ref:`QuickStartPrefixes`
+
+- :ref:`QuickStartSources`.
+
+Return to here once you have completed these steps.
+
+You have chosen an installation prefix, the BSP to build, the tool's
+architecure and prepared the source for the RSB in the previous sections. We
+have chosen :file:`$HOME/quick-start/rtems/5` as the installation prefix, the
+``erc32`` BSP and the SPARC architecture name of ``sparc-rtems5``, and unpacked
+the RSB source in :file:`$HOME/quick-start/src`.
+
+You are now able to build :ref:`BSP Packages` or 3rd party libraries of code if you
+have built a BSP.
+
+RTEMS Packages
+--------------
+
+RTEMS Packages are source packages the RSB build to run on RTEMS. An installed
+package is a set of header files and libraries. Your application include the
+packages header files to make calls to the package's code and include the
+libraries in it's linker options.
+
+RTEMS packages can be part of the RTEMS Project or they can be external
+packages from 3rd parties. RTEMS Project packages include the BSPs and BSD
+Library package called ``libbsd``. External 3rd party packages include
+networking such has ``curl`` or ``libcurl`` to graphics libraries.
+
+Packages can depend on other packages and need to be build in the corret
+order. For example the FreeBSD Library package depends on the BSP package and a
+3rd party library such as ``curl`` depends on the FreeBSD Library package. We
+call this layering a vertical software stack.
+
+RTEMS applications are cross-compiled and this adds complexity when building
+libraries of code. RTEMS Packages build with the RSB manage this complexity for
+you.
+
+Package are libraries so they will not be linked into your application until
+you make calls to the the code and add the library to your application's linker
+command line.
+
+.. QuickStartRSBPackage_BSPStack:
+
+BSP Stack Build
+---------------
+
+A BSP stack build is a single command that uses the RSB to build a BSP software
+stack of:
+
+* Tool suite
+
+* BSP
+
+* Packages
+
+The packages built depend on the BSP and the default will build all packages for a
+BSP.
+
+.. code-block:: none
+
+ cd $HOME/quick-start/src/rsb/rtems
+ ../source-builder/sb-set-builder --prefix=$HOME/quick-start/rtems/5 \
+ --with-rtems-tests=yes bsps/erc32
+
+This command should output something like this:
+
+.. code-block:: none
+
+ RTEMS Source Builder - Set Builder, 5.1.0
+ Build Set: bsps/erc32
+ Build Set: 5/rtems-sparc.bset
+ Build Set: 5/rtems-autotools.bset
+ Build Set: 5/rtems-autotools-internal.bset
+ config: tools/rtems-autoconf-2.69-1.cfg
+ package: autoconf-2.69-x86_64-freebsd12.1-1
+ building: autoconf-2.69-x86_64-freebsd12.1-1
+ sizes: autoconf-2.69-x86_64-freebsd12.1-1: 7.505MB (installed: 0.000B)
+ ...
+ building: protobuf-2.6.1-sparc-rtems5-1
+ sizes: protobuf-2.6.1-sparc-rtems5-1: 228.079MB (installed: 84.408MB)
+ cleaning: protobuf-2.6.1-sparc-rtems5-1
+ reporting: net/protobuf-2.6.1-1.cfg -> protobuf-2.6.1-sparc-rtems5-1.txt
+ reporting: net/protobuf-2.6.1-1.cfg -> protobuf-2.6.1-sparc-rtems5-1.xml
+ staging: protobuf-2.6.1-sparc-rtems5-1 -> $HOME/quick-start/src/rsb/rtems/build/tmp/sb-500-staging
+ cleaning: protobuf-2.6.1-sparc-rtems5-1
+ Build Set: Time 0:00:23.564992
+ Build Set: Time 0:02:27.380299
+ installing: bsps/erc32 -> $HOME/quick-start/rtems/
+ clean staging: bsps/erc32
+ Staging Size: 1.372GB
+ Build Set: Time 0:24:17.83979
+
+The RSB BSP build can be customised with following RSB command line options:
+
+``--with-rtems-tests``:
+ Build the test suite. If ``yes`` is provided all tests in the testsuite are
+ build. If ``no`` is provided no tests are built and if ``samples`` is
+ provided only the sample executables are built, e.g.
+ ``--with-rtems-tests=yes``.
+
+``--with-rtems-smp``:
+ Build with SMP support. The BSP has to have SMP support or this option will
+ fail with an error.
+
+``--with-rtems-bspopts``:
+ Build the BSP with BSP specific options. This is an advanced option. Please
+ refer to the BSP specific details in the :ref:`Board Support Packages
+ (BSPs)` of this manual or the BSP source code in the RTEMS source
+ directory. To supply a list of options quote then list with ``"``, e.g.
+ ``--with-rtems-bspopts="BSP_POWER_DOWN_AT_FATAL_HALT=1"``
+
+Only a limited number of BSPs have RSB support to build as a software stack. To
+see which BSPs are supported run this command:
+
+
+.. code-block:: none
+
+ cd $HOME/quick-start/src/rsb/rtems
+ ../source-builder/sb-set-builder --list-bsets | grep bsps
+
+Package Build
+-------------
+
+Packages are built using RSB build sets. A build set is a set of builds need to
+build a packages. The build steps can be dependencies a package has or it could
+be a stack of software to provide specific functionality, i.e. a build set can
+be a list of build sets. To view the avaliable build sets run this command:
+
+.. code-block:: none
+
+ cd $HOME/quick-start/src/rsb/rtems
+ ../source-builder/sb-set-builder --list-bsets
+
+RTEMS package naming is based on the naming FreeBSD uses in its ports
+collection.
+
+This Quick Start Guide will build the BSD Library or :file:`5/rtems-libbsd`.
+
+An RTEMS package is hosted on RTEMS so the tool suite name needs to be supplied
+using the ``--host`` option, e.g. ``--host=sparc-rtem5``. The BSP needs to be
+provided using the ``--with-rtems-bsp`` option,
+e.g. ``--with-rtems-bsp=erc32``. The commands to build ``libbsd`` for the
+``erc32`` BSP are:
+
+.. code-block:: none
+
+ cd $HOME/quick-start/src/rsb/rtems
+ ../source-builder/sb-set-builder --prefix=$HOME/quick-start/rtems/5 \
+ --host=sparc-rtems5 --with-rtems-bsp=erc32 5/rtems-libbsd
+
+This command should output something like this:
+
+.. code-block:: none
+
+ RTEMS Source Builder - Set Builder, 5.1.0
+ Build Set: 5/rtems-libbsd
+ config: tools/rtems-libbsd-5.cfg
+ package: rtems-libbsd-v3cc039cdac77272a8e16b33ae5a53ccd89edf989-sparc-rtems5-1
+ building: rtems-libbsd-v3cc039cdac77272a8e16b33ae5a53ccd89edf989-sparc-rtems5-1
+ sizes: rtems-libbsd-v3cc039cdac77272a8e16b33ae5a53ccd89edf989-sparc-rtems5-1: 1.199GB (installed: 116.541MB)
+ cleaning: rtems-libbsd-v3cc039cdac77272a8e16b33ae5a53ccd89edf989-sparc-rtems5-1
+ reporting: tools/rtems-libbsd-5.cfg -> rtems-libbsd-v3cc039cdac77272a8e16b33ae5a53ccd89edf989-sparc-rtems5-1.txt
+ reporting: tools/rtems-libbsd-5.cfg -> rtems-libbsd-v3cc039cdac77272a8e16b33ae5a53ccd89edf989-sparc-rtems5-1.xml
+ installing: rtems-libbsd-v3cc039cdac77272a8e16b33ae5a53ccd89edf989-sparc-rtems5-1 -> $HOME/quick-start/rtems/5
+ cleaning: rtems-libbsd-v3cc039cdac77272a8e16b33ae5a53ccd89edf989-sparc-rtems5-1
+ Build Set: Time 0:00:51.898231
+
+.. note::
+
+ Not all packages will build or run with all BSPs. Please ask on the
+ :r:list:`users` if you have any issues.
diff --git a/user/start/sources.rst b/user/start/sources.rst
index 692e2bc..a6e66df 100644
--- a/user/start/sources.rst
+++ b/user/start/sources.rst
@@ -1,7 +1,8 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
-.. Copyright (C) 2019 embedded brains GmbH
+.. Copyright (C) 2019 embedded brains GmbH & Co. KG
.. Copyright (C) 2019 Sebastian Huber
+.. Copyright (C) 2020 Chris Johns
.. _QuickStartSources:
@@ -9,44 +10,126 @@ Obtain the Sources
==================
You have considered and chosen a suitable installation prefix in the previous
-section. We have chosen :file:`$HOME/quick-start/rtems/5` as the installation
-prefix.
+section. We have chosen :file:`$HOME/quick-start/rtems/6` as the installation
+prefix. We will show how to use a released version of RTEMS and then as an
+alternative we will show you using the :ref:`RSB Git repository
+<QuickStartSources_Git>`. Consider using a Git clone if you wish to make
+contributions to the RTEMS Project.
-You need at least two source archives or Git repositories to work with RTEMS.
-You can download the source archives for a released RTEMS version or you can
-clone Git repositories to get all versions of RTEMS including the development
-head.
+You need the RTEMS Source Builder (RSB) to work with RTEMS and we prefer you
+use a released version. A released version of the RSB downloads all source code
+from the RTEMS servers. Each release archives all the referenced source
+providing long term stability as changes in upstream projects do not effect a
+release's build.
-We will clone the Git repositories into :file:`$HOME/quick-start/src`.
+You will need approximately 1.5G bytes of disk space to build the tools, RTEMS
+kernel, network stack and 3rd party packages for the ERC32 BSP.
+
+.. _QuickStartSources_Released:
+
+Releases
+--------
+
+You can download the source archives for a released RTEMS version from RTEMS'
+servers. Releases can be view at https://ftp.rtems.org/pub/rtems/releases with
+the releases listed as a series under a release's major number. For RTEMS 5.1
+the release series is `5 <https://ftp.rtems.org/pub/rtems/releases/5>`_ and the
+release path is https://ftp.rtems.org/pub/rtems/releases/5/5.1.
+
+To work with the archives of a released RTEMS version, simply replace the
+version number ``5`` used throughout this chapter with the version number you
+selected, e.g. ``sparc-rtems4.11``, ``sparc-rtems6``, and so on.
+
+Download and unpack using the ``curl`` and ``tar`` command with these commands:
.. code-block:: none
mkdir -p $HOME/quick-start/src
cd $HOME/quick-start/src
- git clone git://git.rtems.org/rtems-source-builder.git rsb
- git clone git://git.rtems.org/rtems.git
+ curl https://ftp.rtems.org/pub/rtems/releases/5/5.1/sources/rtems-source-builder-5.1.tar.xz | tar xJf -
+
+If ``curl`` does not work consider using ``wget`` or a browser.
+
+The RSB is unpacked under the path ``rtems-source-builder-5.1``. Rename this
+to ``rsb`` to get shorter paths during the tool suite build. To do this run
+these commands:
+
+.. code-block:: none
+
+ cd $HOME/quick-start/src
+ mv rtems-source-builder-5.1 rsb
+
+.. _QuickStartSources_Released_RTEMS:
+
+If you wish to build the RTEMS kernel from source obtain the RTEMS kernel
+sources:
+
+.. code-block:: none
+
+ cd $HOME/quick-start/src
+ curl https://ftp.rtems.org/pub/rtems/releases/5/5.1/sources/rtems-5.1.tar.xz | tar xJf -
+
+.. _QuickStartSources_Git:
+
+Git
+---
-The :file:`rsb` repository clone contains the
-:ref:`RTEMS Source Builder (RSB) <RSB>`. We clone it into
-:file:`rsb` to get shorter paths during the tool suite build. The
-:file:`rtems` repository clone contains the RTEMS sources. These two
-repositories are enough to get started. There are
-`more repositories <https://git.rtems.org>`_ available.
+Alternatively, clone the Git repositories into :file:`$HOME/quick-start/src`.
-Alternatively, you can download the source archives of a released RTEMS
-version.
+A Git repository clone gives you some flexibility with the added complexity of
+needing to use a Git branch to build a released version. With Git you can
+switch between branches to try out different RTEMS versions and you have access
+to the RTEMS source history. The RTEMS Project welcomes contributions. The Git
+repositories enable you to easily create patches and track local changes.
+
+You can clone the Git repository to get all versions of RTEMS including the
+development head. Release branches in Git are kept stable however they may
+differ from a release's source archive.
.. code-block:: none
mkdir -p $HOME/quick-start/src
cd $HOME/quick-start/src
- curl https://ftp.rtems.org/pub/rtems/releases/4.11/4.11.3/rtems-4.11.3.tar.xz | tar xJf -
- curl https://ftp.rtems.org/pub/rtems/releases/4.11/4.11.3/rtems-source-builder-4.11.3.tar.xz | tar xJf -
-
-This quick start chapter focuses on working with the Git repository clones
-since this gives you some flexibility. You can switch between branches to try
-out different RTEMS versions. You have access to the RTEMS source history.
-The RTEMS Project welcomes contributions. The Git repositories enable you to
-easily create patches and track local changes. If you prefer to work with
-archives of a released RTEMS version, then simply replace the version number 5
-used throughout this chapter with the version number you selected, e.g. 4.11.
+ git clone git://git.rtems.org/rtems-source-builder.git rsb
+ git clone git://git.rtems.org/rtems.git
+
+The :file:`rsb` repository clone contains the :ref:`RTEMS Source Builder (RSB)
+<RSB>`. We clone it into :file:`rsb` to get shorter paths during the tool
+suite build. The :file:`rtems` repository clone contains the RTEMS sources.
+These two repositories are enough to get started. There are `more repositories
+<https://git.rtems.org>`_ available.
+
+Offline Download
+----------------
+
+If you have limited Internet access you can download the source before you
+start building. If you are permanently connected to the Internet you do not
+need to do this and the sources will be automatically download on demand when
+needed.
+
+Once the sources have been downloaded you could disconnect your host computer
+from the Internet. It is no longer required to work with RTEMS. To download
+the sources to build the ERC 32 BSP before building run the following commands:
+
+.. code-block:: none
+
+ cd $HOME/quick-start/src/rsb/rtems
+ ../source-builder/sb-set-builder --source-only-download 6/rtems-sparc
+
+This command should output something like this (omitted lines are denoted by
+``...``):
+
+.. code-block:: none
+
+ RTEMS Source Builder - Set Builder, 6 (5e449fb5c2cb)
+ Build Set: 6/rtems-sparc
+ Build Set: 6/rtems-autotools.bset
+ Build Set: 6/rtems-autotools-internal.bset
+ ...
+ download: https://git.rtems.org/rtems-tools/snapshot/rtems-tools-90342feb4dd63d188ce945adfb0a769...<see log> -> sources/rtems-tools-90342feb4dd63d188ce945adfb0a7694a42a65cd.tar.bz2
+ ...
+ Build Sizes: usage: 0.000B total: 264.228MB (sources: 264.186MB, patches: 43.468KB, installed 0.000B)
+ Build Set: Time 0:06:34.357125
+
+If you encounter errors, check your internet connection, firewall settings,
+virus scanners and the availability of the download servers.
diff --git a/user/start/tools.rst b/user/start/tools.rst
index 07dc1e0..3656867 100644
--- a/user/start/tools.rst
+++ b/user/start/tools.rst
@@ -1,126 +1,114 @@
.. SPDX-License-Identifier: CC-BY-SA-4.0
-.. Copyright (C) 2019 embedded brains GmbH
+.. Copyright (C) 2019 embedded brains GmbH & Co. KG
.. Copyright (C) 2019 Sebastian Huber
+.. Copyright (C) 2020 Chris Johns
+.. Copyright (C) 2020 Utkarsh Rai
.. _QuickStartTools:
Install the Tool Suite
======================
-You have chosen an installation prefix and cloned two RTEMS repositories in the
-previous sections. We have chosen :file:`$HOME/quick-start/rtems/5` as the
-installation prefix and cloned the repositories in
-:file:`$HOME/quick-start/src`.
-
-You must select the
-:ref:`target architecture <TargetArchitectures>` for which you need a tool
-suite. In this quick start chapter we choose `sparc-rtems5`. The
-`sparc-rtems5` is the tool suite name for the SPARC architecture and RTEMS
-version 5. The tool suite for RTEMS and the RTEMS sources are tightly coupled.
-For example, do not use a RTEMS version 5 tool suite with RTEMS version 4.11
-sources and vice versa. We use the RSB in two steps. The first step is to
-download additional sources and patches. Afterwards, you could disconnect your
-host computer from the internet. It is no longer required to work with RTEMS.
+You have chosen an installation prefix, the BSP to build, the tool's
+architecure and prepared the source for the RSB in the previous sections. We
+have chosen :file:`$HOME/quick-start/rtems/6` as the installation prefix, the
+``erc32`` BSP and the SPARC architecture name of ``sparc-rtems6``, and unpacked
+the RSB source in :file:`$HOME/quick-start/src`.
+
+The tool suite for RTEMS and the RTEMS sources are tightly coupled. For
+example, do not use a RTEMS version 6 tool suite with RTEMS version 4.11 or 5
+sources and vice versa.
+
+Build and install the tool suite:
.. code-block:: none
cd $HOME/quick-start/src/rsb/rtems
- ../source-builder/sb-set-builder --source-only-download 5/rtems-sparc
+ ../source-builder/sb-set-builder --prefix=$HOME/quick-start/rtems/6 6/rtems-sparc
This command should output something like this (omitted lines are denoted by
-...):
+...). The build host appears as part of the name of the package being
+built. The name you see may vary depending on the host you are using:
.. code-block:: none
- RTEMS Source Builder - Set Builder, 5 (98588a55961a)
- warning: exe: absolute exe found in path: (__unzip) /usr/local/bin/unzip
- Build Set: 5/rtems-sparc
+ RTEMS Source Builder - Set Builder, 6 (5e449fb5c2cb)
+ Build Set: 6/rtems-sparc
...
- download: https://ftp.gnu.org/gnu/gcc/gcc-7.4.0/gcc-7.4.0.tar.xz -> sources/gcc-7.4.0.tar.xz
- ...
- Build Sizes: usage: 0.000B total: 141.738MB (sources: 141.559MB, patches: 183.888KB, installed 0.000B)
- Build Set: Time 0:01:17.613061
+ config: tools/rtems-binutils-2.36.cfg
+ package: sparc-rtems6-binutils-fbb9a7e-x86_64-linux-gnu-1
+ building: sparc-rtems6-binutils-fbb9a7e-x86_64-linux-gnu-1
+ sizes: sparc-rtems6-binutils-fbb9a7e-x86_64-linux-gnu-1: 716.015MB (installed: 163.538MB)
+ cleaning: sparc-rtems6-binutils-fbb9a7e-x86_64-linux-gnu-1
+ reporting: tools/rtems-binutils-2.36.cfg -> sparc-rtems6-binutils-fbb9a7e-x86_64-linux-gnu-1.txt
+ reporting: tools/rtems-binutils-2.36.cfg -> sparc-rtems6-binutils-fbb9a7e-x86_64-linux-gnu-1.xml
+ config: tools/rtems-gcc-10-newlib-head.cfg
+ package: sparc-rtems6-gcc-6051af8-newlib-d10d0d9-x86_64-linux-gnu-1
+ building: sparc-rtems6-gcc-6051af8-newlib-d10d0d9-x86_64-linux-gnu-1
+ ....
+ Build Sizes: usage: 9.607GB total: 2.244GB (sources: 264.186MB, patches: 43.468KB, installed 1.986GB)
+ installing: 6/rtems-sparc -> $HOME/quick-start/rtems/6
+ clean staging: 6/rtems-sparc
+ Staging Size: 5.292MB
+ Build Set: Time 1:01:48.019157
-If you encounter errors in the first step, check your internet connection,
-firewall settings, virus scanners and the availability of the download servers.
-The seconds step is to build and install the tool suite.
+Once the build has successfully completed you can check if the cross C compiler
+works with the following command:
.. code-block:: none
- cd $HOME/quick-start/src/rsb/rtems
- ../source-builder/sb-set-builder --prefix=$HOME/quick-start/rtems/5 5/rtems-sparc
+ $HOME/quick-start/rtems/6/bin/sparc-rtems6-gcc --version
-This command should output something like this (omitted lines are denoted by
-...):
+This command should output something like below. The version informtion helps
+you to identify the exact sources used to build the cross compiler of your
+RTEMS tool suite. In the output you see the version of RTEMS or the hash from
+the RSB repository if you are building using a Git repository clone. The Newlib
+hash is the version of Newlib in the RTEMS's github
+`sourceware-mirror-newlib-cygwin
+<https://github.com/RTEMS/sourceware-mirror-newlib-cygwin>`_ repository. The
+``sources`` and ``patches`` directories created by the RSB contain all the
+source code used.
.. code-block:: none
- RTEMS Source Builder - Set Builder, 5 (98588a55961a)
- warning: exe: absolute exe found in path: (__unzip) /usr/local/bin/unzip
- Build Set: 5/rtems-sparc
- ...
- config: tools/rtems-gcc-7.4.0-newlib-3e24fbf6f.cfg
- package: sparc-rtems5-gcc-7.4.0-newlib-3e24fbf6f-x86_64-freebsd12.0-1
- building: sparc-rtems5-gcc-7.4.0-newlib-3e24fbf6f-x86_64-freebsd12.0-1
- sizes: sparc-rtems5-gcc-7.4.0-newlib-3e24fbf6f-x86_64-freebsd12.0-1: 4.651GB (installed: 879.191MB)
- cleaning: sparc-rtems5-gcc-7.4.0-newlib-3e24fbf6f-x86_64-freebsd12.0-1
- ....
- Build Sizes: usage: 5.618GB total: 1.105GB (sources: 141.559MB, patches: 185.823KB, installed 989.908MB)
- Build Set: Time 0:22:02.262039
+ sparc-rtems6-gcc (GCC) 10.2.1 20210309 (RTEMS 6, RSB 5e449fb5c2cb6812a238f9f9764fd339cbbf05c2, Newlib d10d0d9)
+ Copyright (C) 2020 Free Software Foundation, Inc.
+ This is free software; see the source for copying conditions. There is NO
+ warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
-In case the seconds step was successful, you can check if for example the cross
-C compiler works with the following command:
-.. code-block:: none
- $HOME/quick-start/rtems/5/bin/sparc-rtems5-gcc --version --verbose
+Add ``--verbose`` to the GCC command for the the verbose version details.
-This command should output something like below. In this output the actual
-prefix path was replaced by ``$PREFIX``. The ``compiled by`` line depends on
-the native C++ compiler of your host computer. In the output you see the Git
-hash of the RSB. This helps you to identify the exact sources which were used
-to build the cross compiler of your RTEMS tool suite.
+Need for RTEMS-Specific Cross-Compiler
+---------------------------------------------------------
-.. code-block:: none
+New users are often confused as to why they cannot use their distribution's
+cross-compiler for their target on RTEMS, e.g., the riscv64-linux-gnu or the
+arm-none-eabi-gcc. Below mentioned are some of the reasons for using
+the RTEMS cross-compiler.
- Using built-in specs.
- COLLECT_GCC=$PREFIX/bin/sparc-rtems5-gcc
- COLLECT_LTO_WRAPPER=$PREFIX/bin/../libexec/gcc/sparc-rtems5/7.4.0/lto-wrapper
- sparc-rtems5-gcc (GCC) 7.4.0 20181206 (RTEMS 5, RSB 98588a55961a92f5d27bfd756dfc9e31b2b1bf98, Newlib 3e24fbf6f)
- Copyright (C) 2017 Free Software Foundation, Inc.
- This is free software; see the source for copying conditions. There is NO
- warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ Correct configuration of Newlib
+ Newlib is a C standard library implementation intended for use on embedded
+ systems. Most of the POSIX and libc support for RTEMS is derived from
+ Newlib. The RTEMS cross-compiler configures Newlib correctly for RTEMS.
+
+ Threading in GCC support libraries
+ Several threading packages in GCC such as Go threads (libgo), OpenMP
+ (libgomp), and OpenACC need to be customized according to RTEMS. This is
+ done by the RTEMS specific cross-compiler.
+ Provide preprocessor define __rtems__
+ The ``__rtems__`` preprocessor define is used to provide conditional code
+ compilation in source files that are shared with other projects e.g. in
+ Newlib or imported code from FreeBSD.
- Target: sparc-rtems5
- Configured with: ../gcc-7.4.0/configure --prefix=$PREFIX --bindir=$PREFIX/bin --exec_prefix=$PREFIX --includedir=$PREFIX/include --libdir=$PREFIX/lib --libexecdir=$PREFIX/libexec --mandir=$PREFIX/share/man --infodir=$PREFIX/share/info --datadir=$PREFIX/share --build=x86_64-freebsd12.0 --host=x86_64-freebsd12.0 --target=sparc-rtems5 --disable-libstdcxx-pch --with-gnu-as --with-gnu-ld --verbose --with-newlib --disable-nls --without-included-gettext --disable-win32-registry --enable-version-specific-runtime-libs --disable-lto --enable-newlib-io-c99-formats --enable-newlib-iconv --enable-newlib-iconv-encodings=big5,cp775,cp850,cp852,cp855,cp866,euc_jp,euc_kr,euc_tw,iso_8859_1,iso_8859_10,iso_8859_11,iso_8859_13,iso_8859_14,iso_8859_15,iso_8859_2,iso_8859_3,iso_8859_4,iso_8859_5,iso_8859_6,iso_8859_7,iso_8859_8,iso_8859_9,iso_ir_111,koi8_r,koi8_ru,koi8_u,koi8_uni,ucs_2,ucs_2_internal,ucs_2be,ucs_2le,ucs_4,ucs_4_internal,ucs_4be,ucs_4le,us_ascii,utf_16,utf_16be,utf_16le,utf_8,win_1250,win_1251,win_1252,win_1253,win_1254,win_1255,win_1256,win_1257,win_1258 --enable-threads --disable-plugin --enable-libgomp --enable-languages=c,c++
- Thread model: rtems
- gcc version 7.4.0 20181206 (RTEMS 5, RSB 98588a55961a92f5d27bfd756dfc9e31b2b1bf98, Newlib 3e24fbf6f) (GCC)
- COLLECT_GCC_OPTIONS='--version' '-v' '-mcpu=v7'
- $PREFIX/bin/../libexec/gcc/sparc-rtems5/7.4.0/cc1 -quiet -v -iprefix $PREFIX/bin/../lib/gcc/sparc-rtems5/7.4.0/ help-dummy -quiet -dumpbase help-dummy -mcpu=v7 -auxbase help-dummy -version --version -o /tmp//ccuAN1wc.s
- GNU C11 (GCC) version 7.4.0 20181206 (RTEMS 5, RSB 98588a55961a92f5d27bfd756dfc9e31b2b1bf98, Newlib 3e24fbf6f) (sparc-rtems5)
- compiled by GNU C version 4.2.1 Compatible FreeBSD Clang 6.0.1 (tags/RELEASE_601/final 335540), GMP version 6.1.0, MPFR version 3.1.4, MPC version 1.0.3, isl version isl-0.16.1-GMP
-
- GGC heuristics: --param ggc-min-expand=100 --param ggc-min-heapsize=131072
- COLLECT_GCC_OPTIONS='--version' '-v' '-mcpu=v7'
- $PREFIX/bin/../lib/gcc/sparc-rtems5/7.4.0/../../../../sparc-rtems5/bin/as -v -s --version -o /tmp//ccFVgRAa.o /tmp//ccuAN1wc.s
- GNU assembler version 2.32 (sparc-rtems5) using BFD version (GNU Binutils) 2.32
- GNU assembler (GNU Binutils) 2.32
- Copyright (C) 2019 Free Software Foundation, Inc.
- This program is free software; you may redistribute it under the terms of
- the GNU General Public License version 3 or later.
- This program has absolutely no warranty.
- This assembler was configured for a target of `sparc-rtems5'.
- COMPILER_PATH=$PREFIX/bin/../libexec/gcc/sparc-rtems5/7.4.0/:$PREFIX/bin/../libexec/gcc/:$PREFIX/bin/../lib/gcc/sparc-rtems5/7.4.0/../../../../sparc-rtems5/bin/
- LIBRARY_PATH=$PREFIX/bin/../lib/gcc/sparc-rtems5/7.4.0/:$PREFIX/bin/../lib/gcc/:$PREFIX/bin/../lib/gcc/sparc-rtems5/7.4.0/../../../../sparc-rtems5/lib/
- COLLECT_GCC_OPTIONS='--version' '-v' '-mcpu=v7'
- $PREFIX/bin/../libexec/gcc/sparc-rtems5/7.4.0/collect2 --version $PREFIX/bin/../lib/gcc/sparc-rtems5/7.4.0/../../../../sparc-rtems5/lib/crt0.o -L$PREFIX/bin/../lib/gcc/sparc-rtems5/7.4.0 -L$PREFIX/bin/../lib/gcc -L$PREFIX/bin/../lib/gcc/sparc-rtems5/7.4.0/../../../../sparc-rtems5/lib /tmp//ccFVgRAa.o -lgcc -lc -lgcc
- collect2 version 7.4.0 20181206 (RTEMS 5, RSB 98588a55961a92f5d27bfd756dfc9e31b2b1bf98, Newlib 3e24fbf6f)
- $PREFIX/bin/../lib/gcc/sparc-rtems5/7.4.0/../../../../sparc-rtems5/bin/ld --version $PREFIX/bin/../lib/gcc/sparc-rtems5/7.4.0/../../../../sparc-rtems5/lib/crt0.o -L$PREFIX/bin/../lib/gcc/sparc-rtems5/7.4.0 -L$PREFIX/bin/../lib/gcc -L$PREFIX/bin/../lib/gcc/sparc-rtems5/7.4.0/../../../../sparc-rtems5/lib /tmp//ccFVgRAa.o -lgcc -lc -lgcc
- GNU ld (GNU Binutils) 2.32
- Copyright (C) 2019 Free Software Foundation, Inc.
- This program is free software; you may redistribute it under the terms of
- the GNU General Public License version 3 or (at your option) a later version.
- This program has absolutely no warranty.
- COLLECT_GCC_OPTIONS='--version' '-v' '-mcpu=v7'
+ Multilib variants to match the BSP
+ RTEMS configures GCC to create separate runtime libraries for each
+ supported instruction set, floating point unit, vector unit, word size
+ (e.g. 32-bit and 64-bit), endianness, ABI, processor errata workarounds,
+ and so on in the architecture. These libraries are termed as :ref:`Multilib
+ <TargetArchitectures>` variants. Multilib variants to match the BSP are set
+ by selecting a specific set of machine options using the RTEMS
+ cross-compiler.
generated by cgit v1.2.3 (git 2.25.1) at 2024-04-30 19:01:49 +0000