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