source: rtems-docs/user/start/bsp-build.rst @ 1d6dcf8

Last change on this file since 1d6dcf8 was 1d6dcf8, checked in by Chris Johns <chrisj@…>, on 08/03/22 at 04:24:59

versions: Update user manual

Updates #4695
  • Property mode set to 100644
File size: 11.2 KB
Line 
1.. SPDX-License-Identifier: CC-BY-SA-4.0
2
3.. Copyright (C) 2019 embedded brains GmbH
4.. Copyright (C) 2019 Sebastian Huber
5
6.. _QuickStartBSPBuild:
7
8Build a Board Support Package (BSP)
9===================================
10
11You installed the tool suite in your installation prefix, made ready the source
12for two RTEMS source packages and if you are using a Git clone bootstrapped the
13RTEMS sources in the previous sections.  We installed the tool suite in
14:file:`$HOME/quick-start/rtems/6` and unpacked the source in
15:file:`$HOME/quick-start/src`.
16
17You are now able to build :ref:`Board Support Packages (BSPs) <BSPs>` for all
18architectures you have an installed RTEMS tool suite.  To build applications on
19top of RTEMS, you have to build and install a BSP for your target hardware.  To
20select a proper BSP for your target hardware consult the :ref:`BSPs <BSPs>`
21chapter.  We select the `erc32` BSP. The ``erc32`` BSP uses approximately 2.3G
22bytes of disk space when the testsuite is built and 44M bytes of space when
23installed.
24
25We will first show how to build the BSP using the RSB and then we will show how
26to build the same BSP `manually <QuickStartBSPBuild_Manual>`_. You only need to
27use one of the listed methods to build the BSP.
28
29In the output in this section the base directory :file:`$HOME/quick-start` was
30replaced by ``$BASE``.
31
32.. _QuickStartBSPBuild_RSB:
33
34RSB BSP Build
35-------------
36
37The RSB build of RTEMS does not use the RTEMS source we made ready. It uses the
38RSB source you downloaded in a previous section. If you are using a release RSB
39source archive the BSP built is the released kernel image. If you are using a
40Git clone of the RSB the BSP will be version referenced in the RSB clone.
41
42To build the BSP with all the tests run this command:
43
44.. code-block:: none
45
46    cd $HOME/quick-start/src/rsb/rtems
47    ../source-builder/sb-set-builder --prefix=$HOME/quick-start/rtems/5 \
48        --target=sparc-rtems@rtems-ver-major@ --with-rtems-bsp=erc32 --with-rtems-tests=yes @rtems-ver-major@/rtems-kernel
49
50This command should output something like:
51
52.. code-block:: none
53
54    RTEMS Source Builder - Set Builder, @rtems-ver-majminver@
55    Build Set: @rtems-ver-major@/rtems-kernel
56    config: tools/rtems-kernel-@rtems-ver-major@.cfg
57    package: sparc-rtems@rtems-ver-major@-kernel-erc32-1
58    building: sparc-rtems@rtems-ver-major@-kernel-erc32-1
59    sizes: sparc-rtems@rtems-ver-major@-kernel-erc32-1: 2.279GB (installed: 44.612MB)
60    cleaning: sparc-rtems@rtems-ver-major@-kernel-erc32-1
61    reporting: tools/rtems-kernel-@rtems-ver-major@.cfg -> sparc-rtems@rtems-ver-major@-kernel-erc32-1.txt
62    reporting: tools/rtems-kernel-@rtems-ver-major@.cfg -> sparc-rtems@rtems-ver-major@-kernel-erc32-1.xml
63    installing: sparc-rtems@rtems-ver-major@-kernel-erc32-1 -> $BASE/
64    cleaning: sparc-rtems@rtems-ver-major@-kernel-erc32-1
65    Build Set: Time 0:03:09.896961
66
67The RSB BSP build can be customised with following RSB command line options:
68
69``--with-rtems-tests``:
70    Build the test suite. If ``yes`` is provided all tests in the testsuite are
71    build. If ``no`` is provided no tests are built and if ``samples`` is
72    provided only the sample executables are built, e.g.
73    ``--with-rtems-tests=yes``. The test executables are install under the BSP
74    in the :file:`tests` directory and you can execute them with the
75    :ref:`tester and run command <rtems-tester-command>`.
76
77``--with-rtems-smp``:
78    Build with SMP support. The BSP has to have SMP support or this option will
79    fail with an error.
80
81``--with-rtems-legacy-network``:
82    Build the legacy network software. We recommend you use the current network
83    support in the RTEMS BSP Library (libbsd) unless you need to maintain a
84    legacy product. Do not use the legacy networking software for new
85    developments.
86
87``--with-rtems-bspopts``:
88    Build the BSP with BSP specific options. This is an advanced option. Please
89    refer to the BSP specific details in the :ref:`Board Support Packages
90    (BSPs)` of this manual or the BSP source code in the RTEMS source
91    directory. To supply a list of options quote then list with ``"``, e.g.
92    ``--with-rtems-bspopts="BSP_POWER_DOWN_AT_FATAL_HALT=1"``
93
94If you have built a BSP with the RSB, you can move on to
95:ref:`QuickStartBSPTest`.
96
97.. _QuickStartBSPBuild_Manual:
98
99Manual BSP Build
100----------------
101
102We manually build the BSP in four steps.  The first step is to create a build
103directory.  It must be separate from the RTEMS source directory.  We use
104:file:`$HOME/quick-start/build/b-erc32`.
105
106.. code-block:: none
107
108    mkdir -p $HOME/quick-start/build/b-erc32
109
110The second step is to set your path. Prepend the RTEMS tool suite binary
111directory to your ``$PATH`` throughout the remaining steps. Run the command:
112
113.. code-block:: none
114
115    export PATH=$HOME/quick-start/rtems/@rtems-ver-major@/bin:"$PATH"
116
117Check your installed tools can be found by running:
118
119.. code-block:: none
120
121    command -v sparc-rtems@rtems-ver-major@-gcc && echo "found" || echo "not found"
122
123The output should be:
124
125.. code-block:: none
126
127    found
128
129If ``not found`` is printed the tools are not correctly installed or the path
130has not been correctly set. Check the contents of the path
131:file:`$HOME/quick-start/rtems/@rtems-ver-major@/bin` manually and if
132:file:`sparc-rtems@rtems-ver-major@-gcc` is present the path is wrong. If the
133file cannot be found return to :ref:`QuickStartTools` and install the tools
134again.
135
136The first step is to configure the BSP.  There are various BSP build
137configuration options available.  Some options are BSP-specific.  Each section
138in the INI-style configuration file ``config.ini`` instructs the build system to
139build a particular BSP variant (`sparc/erc32` in our case).  We enable the build
140of the tests with the ``BUILD_TESTS = True`` option and use default values for
141everything else.  For detailed information about the BSP build system, see
142:ref:`BSPBuildSystem`.
143
144.. code-block:: none
145
146    cd $HOME/quick-start/src/rtems
147    echo "[sparc/erc32]" > config.ini
148    echo "BUILD_TESTS = True" >> config.ini
149    ./waf configure --prefix=$HOME/quick-start/rtems/@rtems-ver-major@
150
151The first invocation of ``./waf`` needs a bit of time (e.g. 10 seconds) since an
152internal cache file is populated.  This command should output something like
153this.  In this output the base directory :file:`$HOME/quick-start` was replaced
154by ``$BASE``.
155
156.. code-block:: none
157
158    Setting top to                           : $BASE/quick-start/src/rtems
159    Setting out to                           : $BASE/quick-start/src/rtems/build
160    Configure board support package (BSP)    : sparc/erc32
161    Checking for program 'sparc-rtems@rtems-ver-major@-gcc'  : $BASE/quick-start/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-gcc
162    Checking for program 'sparc-rtems@rtems-ver-major@-g++'  : $BASE/quick-start/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-g++
163    Checking for program 'sparc-rtems@rtems-ver-major@-ar'   : $BASE/quick-start/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-ar
164    Checking for program 'sparc-rtems@rtems-ver-major@-ld'   : $BASE/quick-start/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-ld
165    Checking for program 'ar'                : $BASE/quick-start/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-ar
166    Checking for program 'g++, c++'          : $BASE/quick-start/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-g++
167    Checking for program 'ar'                : $BASE/quick-start/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-ar
168    Checking for program 'gas, gcc'          : $BASE/quick-start/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-gcc
169    Checking for program 'ar'                : $BASE/quick-start/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-ar
170    Checking for program 'gcc, cc'           : $BASE/quick-start/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-gcc
171    Checking for program 'ar'                : $BASE/quick-start/rtems/@rtems-ver-major@/bin/sparc-rtems@rtems-ver-major@-ar
172    Checking for asm flags '-MMD'            : yes
173    Checking for c flags '-MMD'              : yes
174    Checking for cxx flags '-MMD'            : yes
175    Checking for program 'rtems-bin2c'       : $BASE/quick-start/rtems/@rtems-ver-major@/bin/rtems-bin2c
176    Checking for program 'gzip'              : /usr/bin/gzip
177    Checking for program 'rtems-ld'          : $BASE/quick-start/rtems/@rtems-ver-major@/bin/rtems-ld
178    Checking for program 'rtems-syms'        : $BASE/quick-start/rtems/@rtems-ver-major@/bin/rtems-syms
179    Checking for program 'xz'                : $BASE/anaconda3/bin/xz
180    'configure' finished successfully (0.414s)
181
182Building the BSP is the second step.
183
184.. code-block:: none
185
186    cd $HOME/quick-start/src/rtems
187    ./waf
188
189This command should output something like this (omitted lines are denoted by
190...).
191
192.. code-block:: none
193
194    Waf: Entering directory `$BASE/quick-start/src/rtems/build'
195    Waf: Leaving directory `$BASE/quick-start/src/rtems/build'
196    'build' finished successfully (0.085s)
197    Waf: Entering directory `$BASE/quick-start/src/rtems/build/sparc/erc32'
198    [   1/4093] Compiling bsps/shared/dev/serial/mc68681_reg2.c
199    [   2/4093] Compiling bsps/shared/dev/rtc/mc146818a_ioreg.c
200    [   3/4093] Compiling bsps/shared/dev/flash/am29lv160.c
201        ...
202    [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
203    Waf: Leaving directory `$BASE/quick-start/src/rtems/build/sparc/erc32'
204    'build_sparc/erc32' finished successfully (2m14.111s)
205
206The last step is to install the BSP.
207
208.. code-block:: none
209
210    cd $HOME/quick-start/src/rtems
211    ./waf install
212
213This command should output something like this (omitted lines are denoted by
214...).  In this output the base directory :file:`$HOME/quick-start` was replaced
215by ``$BASE``.
216
217.. code-block:: none
218
219    Waf: Entering directory `$BASE/quick-start/src/rtems/build'
220    Waf: Leaving directory `$BASE/quick-start/src/rtems/build'
221    'install' finished successfully (0.081s)
222    Waf: Entering directory `$BASE/quick-start/src/rtems/build/sparc/erc32'
223    + 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)
224    + 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)
225    + 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))
226    ...
227    + 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)
228    + 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)
229    + 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)
230    Waf: Leaving directory `$BASE/quick-start/src/rtems/build/sparc/erc32'
231    'install_sparc/erc32' finished successfully (1.834s))
Note: See TracBrowser for help on using the repository browser.