source: rtems-docs/user/installation/kernel.rst @ ae7a139

Last change on this file since ae7a139 was ae7a139, checked in by Chris Johns <chrisj@…>, on Jul 4, 2016 at 2:45:57 AM

Add the RTEMS Kernel section back in.

  • Property mode set to 100644
File size: 21.5 KB
[ae7a139]1.. comment SPDX-License-Identifier: CC-BY-SA-4.0
3.. comment: Copyright (c) 2016 Chris Johns <>
4.. comment: All rights reserved.
6.. _rtems-kernel:
8RTEMS Kernel
11RTEMS is an open source real-time operating system. As a user you have access
12to all the source code. The ``RTEMS Kernel`` section will show you how you
13build the RTEMS kernel on your host.
15Development Sources
18Create a new location to build the RTEMS kernel:
20.. code-block:: shell
22  $ cd
23  $ cd development/rtems
24  $ mkdir kernel
25  $ cd kernel
27Clone the RTEMS respository:
29.. code-block:: shell
31  $ git clone git:// rtems
32  Cloning into 'rtems'...
33  remote: Counting objects: 483342, done.
34  remote: Compressing objects: 100% (88974/88974), done.
35  remote: Total 483342 (delta 390053), reused 475669 (delta 383809)
36  Receiving objects: 100% (483342/483342), 69.88 MiB | 1.37 MiB/s, done.
37  Resolving deltas: 100% (390053/390053), done.
38  Checking connectivity... done.
40Tools Path Set Up
43We need to set our path to include the RTEMS tools we built in the previous
44section. The RTEMS tools needs to be first in your path because RTEMS provides
45specific versions of the ``autoconf`` and ``automake`` tools. We want to use
46the RTEMS version and not your host's versions:
48.. code-block:: shell
50  $ export PATH=$HOME/development/rtems/4.12/bin:$PATH
52.. _bootstrapping:
57The developers version of the code from git requires we ``bootstrap`` the
58source code. This is an ``autoconf`` and ``automake`` bootstrap to create the
59various files generated by ``autoconf`` and ``automake``. RTEMS does not keep
60these generated files under version control. The bootstrap process is slow so
61to speed it up the RSB provides a command that can perform the bootstrap in
62parallel using your available cores. We need to enter the cloned source
63directory then run the bootsrap commands:
65.. code-block:: shell
67  $ cd rtems
68  $ ./bootstrap -c && ./bootstrap -p && \
69              $HOME/development/rtems/rsb/source-builder/sb-bootstrap
70  removing automake generated files
71  removing configure files
72  removing aclocal.m4 files
73  Generating ./cpukit/dtc/libfdt/
74  Generating ./cpukit/zlib/
75  Generating ./cpukit/libdl/
76  Generating ./cpukit/posix/
77  Generating ./cpukit/pppd/
78  Generating ./cpukit/librpc/
79  Generating ./cpukit/
80  Generating ./cpukit/sapi/
81  Generating ./cpukit/score/
82  Generating ./cpukit/score/cpu/mips/
83  Generating ./cpukit/score/cpu/sh/
84  Generating ./cpukit/score/cpu/sparc/
85  Generating ./cpukit/score/cpu/no_cpu/
86  Generating ./cpukit/score/cpu/arm/
87  Generating ./cpukit/score/cpu/m32c/
88  Generating ./cpukit/score/cpu/moxie/
89  Generating ./cpukit/score/cpu/v850/
90  Generating ./cpukit/score/cpu/sparc64/
91  Generating ./cpukit/score/cpu/or1k/
92  Generating ./cpukit/score/cpu/i386/
93  Generating ./cpukit/score/cpu/nios2/
94  Generating ./cpukit/score/cpu/epiphany/
95  Generating ./cpukit/score/cpu/m68k/
96  Generating ./cpukit/score/cpu/lm32/
97  Generating ./cpukit/score/cpu/powerpc/
98  Generating ./cpukit/score/cpu/bfin/
99  Generating ./cpukit/libpci/
100  Generating ./cpukit/libcrypt/
101  Generating ./cpukit/rtems/
102  Generating ./cpukit/telnetd/
103  Generating ./cpukit/libnetworking/preinstall.a
104   ......
105  Generating ./c/src/lib/libbsp/powerpc/gen5200/
106  Generating ./c/src/lib/libbsp/powerpc/mpc55xxevb/
107  Generating ./c/src/lib/libbsp/bfin/TLL6527M/
108  Generating ./c/src/lib/libbsp/bfin/bf537Stamp/
109  Generating ./c/src/lib/libbsp/bfin/eZKit533/
110  Generating ./c/src/librtems++/
111  Generating ./c/src/libchip/
112  Generating ./c/src/wrapup/
113  Generating ./c/src/ada/
114  RTEMS Source Builder - RTEMS Bootstrap, 4.12 (e645642255cc modified)
115    1/139: autoreconf:
116    2/139: autoreconf: cpukit/
117    3/139: autoreconf: tools/cpu/
118    4/139: autoreconf: tools/cpu/generic/
119    5/139: autoreconf: tools/cpu/sh/
120    6/139: autoreconf: tools/cpu/nios2/
121    7/139: autoreconf: tools/build/
122    8/139: autoreconf: doc/
123   ......
124  124/139: autoreconf: c/src/make/
125  125/139: autoreconf: c/src/librtems++/
126  126/139: autoreconf: c/src/ada-tests/
127  127/139: autoreconf: testsuites/
128  128/139: autoreconf: testsuites/libtests/
129  129/139: autoreconf: testsuites/mptests/
130  130/139: autoreconf: testsuites/fstests/
131  131/139: autoreconf: testsuites/sptests/
132  132/139: autoreconf: testsuites/tmtests/
133  133/139: autoreconf: testsuites/smptests/
134  134/139: autoreconf: testsuites/tools/
135  135/139: autoreconf: testsuites/tools/generic/
136  136/139: autoreconf: testsuites/psxtests/
137  137/139: autoreconf: testsuites/psxtmtests/
138  138/139: autoreconf: testsuites/rhealstone/
139  139/139: autoreconf: testsuites/samples/
140  Bootstrap time: 0:02:47.398824
142Building a BSP
145We build RTEMS in a directory outside of the source tree we have just cloned
146and ``bootstrapped``. You cannot build RTEMS while in the source tree. Lets
147create a suitable directory using the name of the BSP we are going to build:
149.. code-block:: shell
151  $ cd ..
152  $ mkdir erc32
153  $ cd erc32
155Configure RTEMS using the ``configure`` command. We use a full path to
156``configure`` so the object files built contain the absolute path of the source
157files. If you are source level debugging you will be able to access the source
158code to RTEMS from the debugger. We will build for the ``erc32`` BSP with POSIX
159enabled and the networking stack disabled:
161.. code-block:: shell
163  $ $HOME/development/rtems/kernel/rtems/configure --prefix=$HOME/development/rtems/4.12 \
164                     --target=sparc-rtems4.12 --enable-rtemsbsp=erc32 --enable-posix \
165                     --disable-networking
166  checking for gmake... no
167  checking for make... make
168  checking for RTEMS Version...
169  checking build system type... x86_64-pc-linux-gnu
170  checking host system type... x86_64-pc-linux-gnu
171  checking target system type... sparc-unknown-rtems4.12
172  checking for a BSD-compatible install... /usr/bin/install -c
173  checking whether build environment is sane... yes
174  checking for a thread-safe mkdir -p... /bin/mkdir -p
175  checking for gawk... no
176  checking for mawk... mawk
177  checking whether make sets $(MAKE)... yes
178  checking whether to enable maintainer-specific portions of Makefiles... no
179  checking that generated files are newer than configure... done
180   ......
181  checking target system type... sparc-unknown-rtems4.12
182  checking rtems target cpu... sparc
183  checking for a BSD-compatible install... /usr/bin/install -c
184  checking whether build environment is sane... yes
185  checking for sparc-rtems4.12-strip... sparc-rtems4.12-strip
186  checking for a thread-safe mkdir -p... /bin/mkdir -p
187  checking for gawk... no
188  checking for mawk... mawk
189  checking whether make sets $(MAKE)... yes
190  checking whether to enable maintainer-specific portions of Makefiles... no
191  checking that generated files are newer than configure... done
192  configure: creating ./config.status
193  config.status: creating Makefile
195  target architecture: sparc.
196  available BSPs: erc32.
197  'make all' will build the following BSPs: erc32.
198  other BSPs can be built with 'make RTEMS_BSP="bsp1 bsp2 ..."'
200  config.status: creating Makefile
202Build RTEMS using two cores:
204.. code-block:: shell
206  $ make -j 2
207  Making all in tools/build
208  make[1]: Entering directory '/home/chris/development/rtems/kernel/erc32/tools/build'
209  make  all-am
210  make[2]: Entering directory '/home/chris/development/rtems/kernel/erc32/tools/build'
211  gcc -DHAVE_CONFIG_H -I. -I/home/chris/development/rtems/kernel/rtems/tools/build     -g -O2 -MT cklength.o -MD -MP -MF .deps/cklength.Tpo -c -o cklength.o /home/chris/development/rtems/kernel/rtems/tools/build/cklength.c
212  gcc -DHAVE_CONFIG_H -I. -I/home/chris/development/rtems/kernel/rtems/tools/build     -g -O2 -MT eolstrip.o -MD -MP -MF .deps/eolstrip.Tpo -c -o eolstrip.o /home/chris/development/rtems/kernel/rtems/tools/build/eolstrip.c
213  mv -f .deps/cklength.Tpo .deps/cklength.Po
214  mv -f .deps/eolstrip.Tpo .deps/eolstrip.Po
215  gcc -DHAVE_CONFIG_H -I. -I/home/chris/development/rtems/kernel/rtems/tools/build     -g -O2 -MT compat.o -MD -MP -MF .deps/compat.Tpo -c -o compat.o /home/chris/development/rtems/kernel/rtems/tools/build/compat.c
216  gcc -DHAVE_CONFIG_H -I. -I/home/chris/development/rtems/kernel/rtems/tools/build     -g -O2 -MT packhex.o -MD -MP -MF .deps/packhex.Tpo -c -o packhex.o /home/chris/development/rtems/kernel/rtems/tools/build/packhex.c
217  mv -f .deps/compat.Tpo .deps/compat.Po
218  gcc -DHAVE_CONFIG_H -I. -I/home/chris/development/rtems/kernel/rtems/tools/build     -g -O2 -MT unhex.o -MD -MP -MF .deps/unhex.Tpo -c -o unhex.o /home/chris/development/rtems/kernel/rtems/tools/build/unhex.c
219  mv -f .deps/packhex.Tpo .deps/packhex.Po
220  gcc -DHAVE_CONFIG_H -I. -I/home/chris/development/rtems/kernel/rtems/tools/build     -g -O2 -MT rtems-bin2c.o -MD -MP -MF .deps/rtems-bin2c.Tpo -c -o rtems-bin2c.o /home/chris/development/rtems/kernel/rtems/tools/build/rtems-bin2c.c
221  mv -f .deps/unhex.Tpo .deps/unhex.Po
222  gcc -DHAVE_CONFIG_H -I. -I/home/chris/development/rtems/kernel/rtems/tools/build     -g -O2 -MT binpatch.o -MD -MP -MF .deps/binpatch.Tpo -c -o binpatch.o /home/chris/development/rtems/kernel/rtems/tools/build/binpatch.c
223  mv -f .deps/rtems-bin2c.Tpo .deps/rtems-bin2c.Po
224  gcc  -g -O2   -o cklength cklength.o
225  mv -f .deps/binpatch.Tpo .deps/binpatch.Po
226  gcc  -g -O2   -o eolstrip eolstrip.o compat.o
227  gcc  -g -O2   -o packhex packhex.o
228  gcc  -g -O2   -o rtems-bin2c rtems-bin2c.o compat.o
229  gcc  -g -O2   -o unhex unhex.o compat.o
230  gcc  -g -O2   -o binpatch binpatch.o
231  make[2]: Leaving directory '/home/chris/development/rtems/kernel/erc32/tools/build'
232  make[1]: Leaving directory '/home/chris/development/rtems/kernel/erc32/tools/build'
233  Making all in tools/cpu
234  make[1]: Entering directory '/home/chris/development/rtems/kernel/erc32/tools/cpu'
235  Making all in generic
236  make[2]: Entering directory '/home/chris/development/rtems/kernel/erc32/tools/cpu/generic'
237  make[2]: Nothing to be done for 'all'.
238  make[2]: Leaving directory '/home/chris/development/rtems/kernel/erc32/tools/cpu/generic'
239  make[2]: Entering directory '/home/chris/development/rtems/kernel/erc32/tools/cpu'
240  make[2]: Nothing to be done for 'all-am'.
241  make[2]: Leaving directory '/home/chris/development/rtems/kernel/erc32/tools/cpu'
242  make[1]: Leaving directory '/home/chris/development/rtems/kernel/erc32/tools/cpu'
243  Making all in testsuites/tools
244  make[1]: Entering directory '/home/chris/development/rtems/kernel/erc32/testsuites/tools'
245  Making all in generic
246  make[2]: Entering directory '/home/chris/development/rtems/kernel/erc32/testsuites/tools/generic'
247  make[2]: Nothing to be done for 'all'.
248  make[2]: Leaving directory '/home/chris/development/rtems/kernel/erc32/testsuites/tools/generic'
249  make[2]: Entering directory '/home/chris/development/rtems/kernel/erc32/testsuites/tools'
250  make[2]: Nothing to be done for 'all-am'.
251  make[2]: Leaving directory '/home/chris/development/rtems/kernel/erc32/testsuites/tools'
252  make[1]: Leaving directory '/home/chris/development/rtems/kernel/erc32/testsuites/tools'
253  Making all in sparc-rtems4.12/c
254  make[1]: Entering directory '/home/chris/development/rtems/kernel/erc32/sparc-rtems4.12/c'
255  Making all in .
256  make[2]: Entering directory '/home/chris/development/rtems/kernel/erc32/sparc-rtems4.12/c'
257  Configuring RTEMS_BSP=erc32
258  checking for gmake... no
259  checking for make... make
260  checking build system type... x86_64-pc-linux-gnu
261  checking host system type... sparc-unknown-rtems4.12
262   ......
263  sparc-rtems4.12-gcc -B../../../../../erc32/lib/ -specs bsp_specs -qrtems -DHAVE_CONFIG_H -I. -I/home/chris/development/rtems/kernel/rtems/c/src/../../testsuites/samples/nsecs -I.. -I/home/chris/development/rtems/kernel/rtems/c/src/../../testsuites/samples/../support/include   -mcpu=cypress -O2 -g -ffunction-sections -fdata-sections -Wall -Wmissing-prototypes -Wimplicit-function-declaration -Wstrict-prototypes -Wnested-externs -MT init.o -MD -MP -MF .deps/init.Tpo -c -o init.o /home/chris/development/rtems/kernel/rtems/c/src/../../testsuites/samples/nsecs/init.c
264  sparc-rtems4.12-gcc -B../../../../../erc32/lib/ -specs bsp_specs -qrtems -DHAVE_CONFIG_H -I. -I/home/chris/development/rtems/kernel/rtems/c/src/../../testsuites/samples/nsecs -I.. -I/home/chris/development/rtems/kernel/rtems/c/src/../../testsuites/samples/../support/include   -mcpu=cypress -O2 -g -ffunction-sections -fdata-sections -Wall -Wmissing-prototypes -Wimplicit-function-declaration -Wstrict-prototypes -Wnested-externs -MT empty.o -MD -MP -MF .deps/empty.Tpo -c -o empty.o /home/chris/development/rtems/kernel/rtems/c/src/../../testsuites/samples/nsecs/empty.c
265  mv -f .deps/empty.Tpo .deps/empty.Po
266  mv -f .deps/init.Tpo .deps/init.Po
267  sparc-rtems4.12-gcc -B../../../../../erc32/lib/ -specs bsp_specs -qrtems -mcpu=cypress -O2 -g -ffunction-sections -fdata-sections -Wall -Wmissing-prototypes -Wimplicit-function-declaration -Wstrict-prototypes -Wnested-externs -Wl,--gc-sections  -mcpu=cypress   -o nsecs.exe init.o empty.o
268  sparc-rtems4.12-nm -g -n nsecs.exe > nsecs.num
269  sparc-rtems4.12-size nsecs.exe
270     text    data     bss     dec     hex filename
271   121392    1888    6624  129904   1fb70 nsecs.exe
272  cp nsecs.exe nsecs.ralf
273  make[6]: Leaving directory '/home/chris/development/rtems/kernel/erc32/sparc-rtems4.12/ c/erc32/testsuites/samples/nsecs'
274  make[5]: Leaving directory '/home/chris/development/rtems/kernel/erc32/sparc-rtems4.12/ c/erc32/testsuites/samples'
275  make[4]: Leaving directory '/home/chris/development/rtems/kernel/erc32/sparc-rtems4.12/ c/erc32/testsuites/samples'
276  make[4]: Entering directory '/home/chris/development/rtems/kernel/erc32/sparc-rtems4.12/ c/erc32/testsuites'
277  make[4]: Nothing to be done for 'all-am'.
278  make[4]: Leaving directory '/home/chris/development/rtems/kernel/erc32/sparc-rtems4.12/ c/erc32/testsuites'
279  make[3]: Leaving directory '/home/chris/development/rtems/kernel/erc32/sparc-rtems4.12/ c/erc32/testsuites'
280  make[2]: Leaving directory '/home/chris/development/rtems/kernel/erc32/sparc-rtems4.12/ c/erc32'
281  make[1]: Leaving directory '/home/chris/development/rtems/kernel/erc32/sparc-rtems4.12/c'
282  make[1]: Entering directory '/home/chris/development/rtems/kernel/erc32'
283  make[1]: Nothing to be done for 'all-am'.
284  make[1]: Leaving directory '/home/chris/development/rtems/kernel/erc32'
286Installing A BSP
289All that remains to be done is to install the kernel. Installing RTEMS copies
290the API headers and architecture specific libraries to a locaiton under the
291`prefix` you provide. You can install any number of BSPs under the same
292`prefix`. We recommend you have a separate `prefix` for different versions of
293RTEMS. Do not mix versions of RTEMS under the same `prefix`. Make installs
294RTEMS with the following command:
296.. code-block:: shell
298  $ make install
299  Making install in tools/build
300  make[1]: Entering directory '/home/chris/development/rtems/kernel/erc32/tools/build'
301  make[2]: Entering directory '/home/chris/development/rtems/kernel/erc32/tools/build'
302  /bin/mkdir -p '/home/chris/development/rtems/4.12/bin'
303  /usr/bin/install -c cklength eolstrip packhex unhex rtems-bin2c '/home/chris/development/rtems/4.12/bin'
304  /bin/mkdir -p '/home/chris/development/rtems/4.12/bin'
305  /usr/bin/install -c install-if-change '/home/chris/development/rtems/4.12/bin'
306  make[2]: Nothing to be done for 'install-data-am'.
307  make[2]: Leaving directory '/home/chris/development/rtems/kernel/erc32/tools/build'
308  make[1]: Leaving directory '/home/chris/development/rtems/kernel/erc32/tools/build'
309  Making install in tools/cpu
310  make[1]: Entering directory '/home/chris/development/rtems/kernel/erc32/tools/cpu'
311  Making install in generic
312  make[2]: Entering directory '/home/chris/development/rtems/kernel/erc32/tools/cpu/generic'
313  make[3]: Entering directory '/home/chris/development/rtems/kernel/erc32/tools/cpu/generic'
314  make[3]: Nothing to be done for 'install-exec-am'.
315  make[3]: Nothing to be done for 'install-data-am'.
316  make[3]: Leaving directory '/home/chris/development/rtems/kernel/erc32/tools/cpu/generic'
317  make[2]: Leaving directory '/home/chris/development/rtems/kernel/erc32/tools/cpu/generic'
318  make[2]: Entering directory '/home/chris/development/rtems/kernel/erc32/tools/cpu'
319  make[3]: Entering directory '/home/chris/development/rtems/kernel/erc32/tools/cpu'
320  make[3]: Nothing to be done for 'install-exec-am'.
321  make[3]: Nothing to be done for 'install-data-am'.
322  make[3]: Leaving directory '/home/chris/development/rtems/kernel/erc32/tools/cpu'
323  make[2]: Leaving directory '/home/chris/development/rtems/kernel/erc32/tools/cpu'
324  make[1]: Leaving directory '/home/chris/development/rtems/kernel/erc32/tools/cpu
325   ......
326  make[1]: Leaving directory '/home/chris/development/rtems/kernel/erc32/sparc-rtems4.12/c'
327  make[1]: Entering directory '/home/chris/development/rtems/kernel/erc32'
328  make[2]: Entering directory '/home/chris/development/rtems/kernel/erc32'
329  make[2]: Nothing to be done for 'install-exec-am'.
330  /bin/mkdir -p '/home/chris/development/rtems/4.12/make'
331  /usr/bin/install -c -m 644 /home/chris/development/rtems/kernel/rtems/make/main.cfg /home/chris/development/rtems/kernel/rtems/make/leaf.cfg '/home/chris/development/rtems/4.12/make'
332  /bin/mkdir -p '/home/chris/development/rtems/4.12/share/rtems4.12/make/Templates'
333  /usr/bin/install -c -m 644 /home/chris/development/rtems/kernel/rtems/make/Templates/Makefile.dir /home/chris/development/rtems/kernel/rtems/make/Templates/Makefile.leaf /home/chris/development/rtems/kernel/rtems/make/Templates/Makefile.lib '/home/chris/development/rtems/4.12/share/rtems4.12/make/Templates'
334  /bin/mkdir -p '/home/chris/development/rtems/4.12/make/custom'
335  /usr/bin/install -c -m 644 /home/chris/development/rtems/kernel/rtems/make/custom/default.cfg '/home/chris/development/rtems/4.12/make/custom'
336  make[2]: Leaving directory '/home/chris/development/rtems/kernel/erc32'
337  make[1]: Leaving directory '/home/chris/development/rtems/kernel/erc32'
339Contributing Patches
342RTEMS welcomes fixes to bugs and new features. The RTEMS Project likes to have
343bugs fixed against a ticket created on our :r:url:`devel`. Please raise a
344ticket if you have a bug. Any changes that are made can be tracked against the
345ticket. If you want to add a new a feature please post a message to
346:r:list:`devel` describing what you would like to implement. The RTEMS
347maintainer will help decide if the feature is in the best interest of the
348project. Not everything is and the maintainers need to evalulate how much
349effort it is to maintain the feature. Once accepted into the source tree it
350becomes the responsibility of the maintainers to keep the feature updated and
353Changes to the source tree are tracked using git. If you have not made changes
354and enter the source tree and enter a git status command you will see nothing
355has changed:
357.. code-block:: shell
359  $ cd ../rtems
360  $ git status
361  On branch master
362  Your branch is up-to-date with 'origin/master'.
363  nothing to commit, working directory clean
365We will make a change to the source code. In this example I change the help
366message to the RTEMS shell's ``halt`` command. Running the same git status
367command reports:
369.. code-block:: shell
371  $ git status
372  On branch master
373  Your branch is up-to-date with 'origin/master'.
374  Changes not staged for commit:
375    (use "git add <file>..." to update what will be committed)
376    (use "git checkout -- <file>..." to discard changes in working directory)
378          modified:   cpukit/libmisc/shell/main_halt.c
380  no changes added to commit (use "git add" and/or "git commit -a")
382As an example I have a ticket open and the ticket number is 9876. I commit the
383change with the follow git command:
385.. code-block:: shell
387  $ git commit cpukit/libmisc/shell/main_halt.c
389An editor is opened and I enter my commit message. The first line is a title
390and the following lines form a body. My message is:
392.. code-block:: shell
394  shell: Add more help detail to the halt command.
396  Closes #9876.
398  # Please enter the commit message for your changes. Lines starting
399  # with '#' will be ignored, and an empty message aborts the commit.
400  # Explicit paths specified without -i or -o; assuming --only paths...
401  #
402  # Committer: Chris Johns <>
403  #
404  # On branch master
405  # Your branch is up-to-date with 'origin/master'.
406  #
407  # Changes to be committed:
408  #       modified:   cpukit/libmisc/shell/main_halt.c
410When you save and exit the editor git will report the commit's status:
412.. code-block:: shell
414  $ git commit cpukit/libmisc/shell/main_halt.c
415  [master 9f44dc9] shell: Add more help detail to the halt command.
416   1 file changed, 1 insertion(+), 1 deletion(-)
418You can either email the patch to :r:list:`devel` with the following git
419command, and it is `minus one` on the command line:
421.. code-block:: shell
423  $ git send-email -1
424   <add output here>
426Or you can ask git to create a patch file using:
428.. code-block:: shell
430  $ git format-patch -1
431  0001-shell-Add-more-help-detail-to-the-halt-command.patch
433This patch can be attached to a ticket.
Note: See TracBrowser for help on using the repository browser.