source: rtems-docs/user/tools/bsp-builder.rst @ 60a6d6e

5
Last change on this file since 60a6d6e was 60a6d6e, checked in by Sebastian Huber <sebastian.huber@…>, on 11/09/17 at 09:22:24

Change RTEMS version to 5

Update #3220.
  • Property mode set to 100644
File size: 18.2 KB
Line 
1.. comment SPDX-License-Identifier: CC-BY-SA-4.0
2
3.. comment: Copyright (c) 2017 Chris Johns <chrisj@rtems.org>
4.. comment: All rights reserved.
5
6RTEMS BSP Builder
7=================
8
9.. index:: Tools, rtems-bsp-builder
10
11The RTEMS BSP Builder is an RTEMS developer tool to build RTEMS in ways users
12do not to test changes to RTEMS. RTEMS has large number of architectures, board
13support packages and configuration options. This tool provides a standard way
14to test a change.
15
16Developer Workflows
17-------------------
18
19There are a number of RTEMS developers each with a different view or expertise
20in RTEMS. Developers can work in the generic areas such as scheduling, file
21systems or the shell, or users can become developers adding a new BSP, or even
22a new port to a new architecture. A common approach for all these developers is
23to select a BSP and to work with that BSP. Developers working in a generic
24areas of RTEMS tend to select a BSP that has good simulator support with good
25debugging such as QEMU, while developers of a new BSP or a new port tend to
26work on target hardware. This type of development does not check the other
27architectures, BSP, and build options and a change may change the number of
28warnings or introduce build errors. It is important for the RTEMS project to
29have developers fix these issues before pushing the changes to the master
30repository to avoid breaking the code for other developers. It is best for a
31developer to resolve as many issues as they work on changes because comming
32back to a problem often proves difficult.
33
34The RTEMS BSP Builder forms part of a developers workflow where patches are
35tested before being pushed to the repository.
36
37Build Characteristics
38---------------------
39
40Build characteristic are the various parts of a build that can varied changing
41what is built. RTEMS can vary builds based on:
42
43#. Architecture
44
45#. Board Support Package (BSP)
46
47#. Build options
48
49#. BSP Options
50
51The BSP Builder provides a template of builds to try and reduce the possble
52combinations to something manageable. It is not realistic to build all possible
53combinations on a single machine in reasonible time.
54
55The RTEMS BSP Builder specifies it builds in terms of:
56
57#. Profiles
58
59#. Architectures
60
61#. BSPs
62
63#. Builds
64
65The RTEMS BSP Builder builds are created by user options that vary these parameters.
66
67Profiles
68^^^^^^^^
69
70A profile is named collection of architectures and board support packages. When
71the RTEMS BSP Builder is asked to build a specific profile it builds the BSPs
72in the specified architectures.
73
74The default configuration provides standard profiles for :ref:`Tiers`. They are:
75
76#. ``tier-1`` (default)
77
78#. ``tier-2``
79
80#. ``tier-3``
81
82#. ``tier-4``
83
84The ``everythings`` profile allows all BSPs to be built.
85
86Builds
87^^^^^^
88
89A build is a list of builds or a build set and each BSP in a profile,
90architecture of BSP is built with.
91
92The default configuration provides standard builds based around the commonly
93varied configure options.
94
95The builds are:
96
97#. ``all`` (default)
98
99#. ``tests``
100
101#. ``standard``, also ``no-tests``
102
103#. ``debug``
104
105#. ``profiling``
106
107#. ``smp``
108
109#. ``smp-debug``
110
111#. ``posix``
112
113#. ``no-posix``
114
115#. ``posix-debug``
116
117#. ``posix-profiling``
118
119#. ``network``
120
121#. ``no-network``
122
123#. ``network-debug``
124
125#. ``smp-network``
126
127#. ``smp-network-debug``
128
129All Build
130~~~~~~~~~
131
132The ``all`` build is:
133
134- ``debug``
135- ``profiling``
136- ``smp``
137- ``smp-debug``
138- ``posix``
139- ``no-posix``
140- ``posix-debug``
141- ``posix-profiling``
142- ``network``
143- ``no-network``
144- ``network-debug``
145- ``smp-network``
146- ``smp-network-debug``
147
148A build maps to specific configuration options. The mappings are:
149
150 +-----------------------+-----------------------------------------------------+
151 | ``debug``             | ``config:base``, ``config:debug``                   |
152 +-----------------------+-----------------------------------------------------+
153 | ``profiling``         | ``config:base``, ``config:profiling``               |
154 +-----------------------+-----------------------------------------------------+
155 | ``smp``               | ``config:base``, ``config:smp``                     |
156 +-----------------------+-----------------------------------------------------+
157 | ``smp-debug``         | ``config:base``, ``config:smp``, ``config:debug``   |
158 +-----------------------+-----------------------------------------------------+
159 | ``posix``             | ``config:base``, ``config:posix``                   |
160 +-----------------------+-----------------------------------------------------+
161 | ``no-posix``          | ``config:base``, ``config:no-posix``                |
162 +-----------------------+-----------------------------------------------------+
163 | ``posix-debug``       | ``config:base``, ``config:posix``, ``config:debug`` |
164 +-----------------------+-----------------------------------------------------+
165 | ``posix-profiling``   | ``config:base``, ``config:posix``,                  |
166 |                       | ``config:profiling``                                |
167 +-----------------------+-----------------------------------------------------+
168 | ``network``           | ``config:base``, ``config:network``                 |
169 +-----------------------+-----------------------------------------------------+
170 | ``no-network``        | ``config:base``, ``config:no-network``              |
171 +-----------------------+-----------------------------------------------------+
172 | ``network-debug``     | ``config:base``, ``config:network``,                |
173 |                       | ``config:debug``                                    |
174 +-----------------------+-----------------------------------------------------+
175 | ``smp-network``       | ``config:base``, ``config:smp``, ``config:network`` |
176 +-----------------------+-----------------------------------------------------+
177 | ``smp-network-debug`` | ``config:base``, ``config:smp``,                    |
178 |                       | ``config:network``, ``config:debug``                |
179 +-----------------------+-----------------------------------------------------+
180
181Build Configurations
182--------------------
183
184Build configurations are ``configure`` options. These are mapped to the various
185builds. The configurations are:
186
187 +------------------+----------------------------------------------------------+
188 | ``base``         | ``--target=@ARCH@-rtems@RTEMS_VERSION@``                 |
189 |                  | ``--enable-rtemsbsp=@BSP@``                              |
190 |                  | ``--prefix=@PREFIX@``                                    |
191 +------------------+----------------------------------------------------------+
192 | ``tests``        | ``--enable-tests``                                       |
193 +------------------+----------------------------------------------------------+
194 | ``debug``        | ``--enable-debug``                                       |
195 +------------------+----------------------------------------------------------+
196 | ``no-debug``     | ``--disable-debug``                                      |
197 +------------------+----------------------------------------------------------+
198 | ``profiling``    | ``--enable-profiling``                                   |
199 +------------------+----------------------------------------------------------+
200 | ``no-profiling`` | ``--disable-profiling``                                  |
201 +------------------+----------------------------------------------------------+
202 | ``smp``          | ``--enable-smp``                                         |
203 +------------------+----------------------------------------------------------+
204 | ``no-smp``       | ``--disable-smp``                                        |
205 +------------------+----------------------------------------------------------+
206 | ``posix``        | ``--enable-posix``                                       |
207 +------------------+----------------------------------------------------------+
208 | ``no-posix``     | ``--disable-posix``                                      |
209 +------------------+----------------------------------------------------------+
210 | ``network``      | ``--enable-networking``                                  |
211 +------------------+----------------------------------------------------------+
212 | ``no-network``   | ``--disable-networking``                                 |
213 +------------------+----------------------------------------------------------+
214
215Performance
216-----------
217
218The RTEMS BSP Builder is designed to extract the maximum performance from your
219hardware when building RTEMS. The RTEMS build system is based on ``autoconf``,
220``automake`` and GNU ``make``. Building consists of two phases:
221
222#. Configuring
223
224#. Building
225
226The Configuring phase and the start of the Build phase runs autoconf's
227``configure`` scripts. These execute as a single linear process and are not run
228in parallel even if you specify more than one job to ``make``. The configure
229part of a build is approximately 30% of the total time and higher if building
230the tests. Performing a single build at a time will not fully utilized a
231multi-core machine because of the large amount of time the system is idle.
232
233The RTEMS BSP Builder can run more than one build in parallel. A build can also
234request ``make`` run its build with more than one job. The ``--jobs`` option
235lets a user specify the number of build jobs to run at once and the number of
236``make`` jobs each build runs with. Together these options can fully load a
237system and can overload a machine.
238
239Tuning the best ratio of buld jobs to make jobs requires running some builds
240and observing the system's performance. If the build job count is too low the
241system will show idle periods and if you have too many build jobs with too many
242make jobs the system will have too many processing running and the operating
243system's overheads in administting too processes at once lowers the overall
244performance.
245
246A fast eight core machine where the operating system shows sixteen cores can
247support a build option of ``--jobs=5/10``. The machine will be fully loaded the
248average build time is around 18 seconds.
249
250The type of build selected effects the optimum jobs option. For example
251building the tests changes the percentage of time spent configuring copmared to
252bulding so the make jobs parameter becomes a dominant factor. Lowering the make
253jobs value avoids having too many active processes running at once.
254
255Command
256-------
257
258:program:`rtems-bsp-builder` [options]
259
260.. option:: -?
261
262   Display a compact help.
263
264.. option:: -h, --help
265
266   Display the full help.
267
268.. option:: --prefix
269
270   Prefix to pass to configure when building a BSP.
271
272.. option:: --rtems-tools
273
274   The path the RTEMS tools such as the C compiler. This option avoid polluting
275   your path. This path is to the tool's prefix used to build and install the
276   tools and not exact path to an executable.
277
278.. option:: --rtems
279
280   The path the RTEMS source tree to build.
281
282.. option:: --build-path
283
284   The path to build the BSP and place the build output. This can be any path
285   and away from your current directory or the RTEMS source code. The storage
286   does not need to be fast like an SSD.
287
288.. option:: --log
289
290   The log file.
291
292.. option:: --config-report
293
294   Print a configuration report and exit.
295
296.. option:: --warnings-report
297
298   Create a warnings report once all builds have finished.
299
300.. option:: --stop-on-error
301
302   Stop the build on an error. The default is to build all the builds for a
303   profile.
304
305.. option:: --no-clean
306
307   Do not remove the build once finished. This option lets you inspect the
308   built output. The amount of output can be large and disks can fill with this
309   option.
310
311.. option:: --profiles
312
313   Build the comma separated list of profiles. The default is ``tier-1``.
314
315.. option:: --arch
316
317   A comma separated list of architecures to build using the selected build.
318
319.. option:: --bsp
320
321   A comma separated list of BSPs to build where a BSP is of the format
322   ``arch/bsp`` using the selected build.
323
324.. option:: --build
325
326   The build to be used. The default is ``all``. See ``--config-report`` for a
327   list of vlaid builds.
328
329.. option:: --jobs
330
331   The jobs options where the format is ``build-jobs/make-jobs``. The default
332   is ``1/num-cores`` where ``num-cores`` is the operating system reported
333   number of cores.
334
335.. option:: --dry-run
336
337   Do not do the actual builds just show what would be built.
338
339Examples
340^^^^^^^^
341
342The following is a *tier-1* profile build of *all* on a machine where all the
343source and tools are located on fast SSD disks and the build happens on a
344spinning disk mounted under `build`. The build uses a development source tree
345that is bootstrapped and ready to build. The source can have local patches that
346need to be regression tested:
347
348.. code-block:: shell
349
350  $ /opt/rtems/5/bin/rtems-bsp-builder --build-path=/build/rtems \
351            --rtems-tools=/opt/work/rtems/5 \
352            --rtems=/opt/work/chris/rtems/kernel/rtems.git \
353            --profiles=tier-1 \
354            --jobs=5/10
355  RTEMS Tools Project - RTEMS Kernel BSP Builder, 5.not_released
356  Profile(s): tier-1
357  Cleaning: bsp-builds
358  [  1/655] arm/altcycv_devkit (debug)                         Start
359  [  1/655] arm/altcycv_devkit (debug)                         Creating: bsp-builds/arm/altcycv_devkit.debug
360  [  2/655] arm/altcycv_devkit (no-posix)                      Start
361  [  2/655] arm/altcycv_devkit (no-posix)                      Creating: bsp-builds/arm/altcycv_devkit.no-posix
362  [  3/655] arm/altcycv_devkit (posix)                         Start
363  [  1/655] arm/altcycv_devkit (debug)                         Configuring
364  [  3/655] arm/altcycv_devkit (posix)                         Creating: bsp-builds/arm/altcycv_devkit.posix
365  [  2/655] arm/altcycv_devkit (no-posix)                      Configuring
366  [  4/655] arm/altcycv_devkit (posix-debug)                   Start
367  [  1/655] arm/altcycv_devkit (debug)                         Building
368  [  3/655] arm/altcycv_devkit (posix)                         Configuring
369  [  4/655] arm/altcycv_devkit (posix-debug)                   Creating: bsp-builds/arm/altcycv_devkit.posix-debug
370  [  2/655] arm/altcycv_devkit (no-posix)                      Building
371  [  5/655] arm/altcycv_devkit (posix-profiling)               Start
372  [  4/655] arm/altcycv_devkit (posix-debug)                   Configuring
373  [  3/655] arm/altcycv_devkit (posix)                         Building
374   ....
375  [654/655] sparc/ngmp (posix-profiling)                       PASS
376  [654/655] sparc/ngmp (posix-profiling)                       Warnings:0  exes:0  objs:0  libs:0
377  [654/655] sparc/ngmp (posix-profiling)                       Finished (duration:0:01:49.002189)
378  [654/655] sparc/ngmp (posix-profiling)                       Status: Pass:  655  Fail:    0 (configure:0 build:0)
379  [655/655] sparc/ngmp (profiling)                             PASS
380  [655/655] sparc/ngmp (profiling)                             Warnings:0  exes:0  objs:0  libs:0
381  [655/655] sparc/ngmp (profiling)                             Finished (duration:0:01:260.002098)
382  [655/655] sparc/ngmp (profiling)                             Status: Pass:  655  Fail:    0 (configure:0 build:0)
383  [651/655] sparc/ngmp (no-posix)                              Cleaning: bsp-builds/sparc/ngmp.no-posix
384  [652/655] sparc/ngmp (posix)                                 Cleaning: bsp-builds/sparc/ngmp.posix
385  [653/655] sparc/ngmp (posix-debug)                           Cleaning: bsp-builds/sparc/ngmp.posix-debug
386  [654/655] sparc/ngmp (posix-profiling)                       Cleaning: bsp-builds/sparc/ngmp.posix-profiling
387  [655/655] sparc/ngmp (profiling)                             Cleaning: bsp-builds/sparc/ngmp.profiling
388  Total: Warnings:31689  exes:6291  objs:793839  libs:37897
389  Failures:
390   No failure(s)
391  Average BSP Build Time: 0:00:18.165000
392  Total Time 3:41:48.075006
393  Passes: 655   Failures: 0
394
395To build a couple of BSPs you are interested in with tests:
396
397.. code-block:: shell
398
399  $ /opt/rtems/5/bin/rtems-bsp-builder --build-path=/build/rtems \
400            --rtems-tools=/opt/work/rtems/5 \
401            --rtems=/opt/work/chris/rtems/kernel/rtems.git \
402            ----log=lpc-log \
403            --bsp=arm/lpc2362,arm/lpc23xx_tli800 \
404            --build=tests \
405            --jobs=5/12
406  RTEMS Tools Project - RTEMS Kernel BSP Builder, 5.not_released
407  BSPS(s): arm/lpc2362, arm/lpc23xx_tli800
408  Cleaning: bsp-builds
409  [1/2] arm/lpc2362 (tests)        Start
410  [1/2] arm/lpc2362 (tests)        Creating: bsp-builds/arm/lpc2362.tests
411  [2/2] arm/lpc23xx_tli800 (tests) Start
412  [2/2] arm/lpc23xx_tli800 (tests) Creating: bsp-builds/arm/lpc23xx_tli800.tests
413  [1/2] arm/lpc2362 (tests)        Configuring
414  [2/2] arm/lpc23xx_tli800 (tests) Configuring
415  [1/2] arm/lpc2362 (tests)        Building
416  [2/2] arm/lpc23xx_tli800 (tests) Building
417  [1/2] arm/lpc2362 (tests)        FAIL
418  [1/2] arm/lpc2362 (tests)        Warnings:74  exes:58  objs:1645  libs:74
419  [1/2] arm/lpc2362 (tests)        Finished (duration:0:01:31.708252)
420  [1/2] arm/lpc2362 (tests)        Status: Pass:    0  Fail:    2 (configure:0 build:2)
421  [2/2] arm/lpc23xx_tli800 (tests) FAIL
422  [2/2] arm/lpc23xx_tli800 (tests) Warnings:74  exes:51  objs:1632  libs:74
423  [2/2] arm/lpc23xx_tli800 (tests) Finished (duration:0:01:31.747582)
424  [2/2] arm/lpc23xx_tli800 (tests) Status: Pass:    0  Fail:    2 (configure:0 build:2)
425  [1/2] arm/lpc2362 (tests)        Cleaning: bsp-builds/arm/lpc2362.tests
426  [2/2] arm/lpc23xx_tli800 (tests) Cleaning: bsp-builds/arm/lpc23xx_tli800.tests
427  Total: Warnings:74  exes:109  objs:3277  libs:148
428  Failures:
429     1 tests arm/lpc2362 build:
430        configure: /opt/work/chris/rtems/kernel/rtems.git/configure --target\
431        =arm-rtems5 --enable-rtemsbsp=lpc2362 --prefix=/opt/rtems/5\
432        --enable-tests
433       error: ld/collect2:0 error: math.exe section '.rodata' will not fit
434              in region 'ROM_INT'; region 'ROM_INT' overflowed by 7284 bytes
435
436     2 tests arm/lpc23xx_tli800 build:
437        configure: /opt/work/chris/rtems/kernel/rtems.git/configure --target\
438        =arm-rtems5 --enable-rtemsbsp=lpc23xx_tli800\
439        --prefix=/opt/rtems/5 --enable-tests
440       error: ld/collect2:0 error: math.exe section '.text' will not fit in
441              region 'ROM_INT'; region 'ROM_INT' overflowed by 13972 bytes
442
443  Average BSP Build Time: 0:00:46.658257
444  Total Time 0:01:33.316514
445  Passes: 0   Failures: 2
446
447The summary report printed shows both BSP builds failed with the error detail
448shown. In this case both are linker related errors where the test do not fit
449into the target's available resources.
Note: See TracBrowser for help on using the repository browser.