From 1d6dcf811f6c7a54da6b214ddd6d3ca8a372bd47 Mon Sep 17 00:00:00 2001 From: Chris Johns Date: Wed, 3 Aug 2022 14:24:59 +1000 Subject: versions: Update user manual Updates #4695 --- user/start/app.rst | 100 +++++++++++++++++++++++------------------------ user/start/bsp-build.rst | 95 ++++++++++++++++++++++---------------------- 2 files changed, 98 insertions(+), 97 deletions(-) (limited to 'user/start') diff --git a/user/start/app.rst b/user/start/app.rst index 19ae3e1..ce9a44d 100644 --- a/user/start/app.rst +++ b/user/start/app.rst @@ -8,7 +8,7 @@ Build Your Application ====================== You tested a BSP in the previous section. We built the ``erc32`` BSP -and it is installed under :file:`$HOME/quick-start/rtems/6`. +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 `_ build system. @@ -148,45 +148,45 @@ 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 : 6 - Architectures : sparc-rtems6 - Board Support Package (BSP) : sparc-rtems6-erc32 - Show commands : no - Long commands : no - Checking for program 'sparc-rtems6-gcc' : $BASE/rtems/6/bin/sparc-rtems6-gcc - Checking for program 'sparc-rtems6-g++' : $BASE/rtems/6/bin/sparc-rtems6-g++ - Checking for program 'sparc-rtems6-gcc' : $BASE/rtems/6/bin/sparc-rtems6-gcc - Checking for program 'sparc-rtems6-ld' : $BASE/rtems/6/bin/sparc-rtems6-ld - Checking for program 'sparc-rtems6-ar' : $BASE/rtems/6/bin/sparc-rtems6-ar - Checking for program 'sparc-rtems6-nm' : $BASE/rtems/6/bin/sparc-rtems6-nm - Checking for program 'sparc-rtems6-objdump' : $BASE/rtems/6/bin/sparc-rtems6-objdump - Checking for program 'sparc-rtems6-objcopy' : $BASE/rtems/6/bin/sparc-rtems6-objcopy - Checking for program 'sparc-rtems6-readelf' : $BASE/rtems/6/bin/sparc-rtems6-readelf - Checking for program 'sparc-rtems6-strip' : $BASE/rtems/6/bin/sparc-rtems6-strip - Checking for program 'sparc-rtems6-ranlib' : $BASE/rtems/6/bin/sparc-rtems6-ranlib - Checking for program 'rtems-ld' : $BASE/rtems/6/bin/rtems-ld - Checking for program 'rtems-tld' : $BASE/rtems/6/bin/rtems-tld - Checking for program 'rtems-syms' : $BASE/rtems/6/bin/rtems-syms - Checking for program 'rtems-bin2c' : $BASE/rtems/6/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-rtems6-gcc) : 10.2.1 20210309 (RTEMS 6, 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 + 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: @@ -198,25 +198,25 @@ The output will be something close to: .. code-block:: none - Waf: Entering directory `$BASE/app/hello/build/sparc-rtems6-erc32' + 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-rtems6-erc32/hello.exe - Waf: Leaving directory `$BASE/app/hello/build/sparc-rtems6-erc32' - 'build-sparc-rtems6-erc32' finished successfully (0.183s) + [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 - $HOME/quick-start/rtems/6/bin/rtems-run --rtems-bsps=erc32-sis build/sparc-rtems6-erc32/hello.exe + $HOME/quick-start/rtems/@rtems-ver-major@/bin/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, 6.0.not_released - Command Line: $BASE/quick-start/rtems/6/bin/rtems-run --rtems-bsps=erc32-sis build/sparc-rtems6-erc32/hello.exe + 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) @@ -226,7 +226,7 @@ The output will be something close to: ERC32 emulation enabled - Loaded build/sparc-rtems6-erc32/hello.exe, entry 0x02000000 + Loaded build/sparc-rtems@rtems-ver-major@-erc32/hello.exe, entry 0x02000000 Hello World @@ -234,9 +234,9 @@ The output will be something close to: fatal source: 5 (RTEMS_FATAL_SOURCE_EXIT) fatal code: 0 (0x00000000) RTEMS version: 6.0.0.586e06ec6222f1cd1f005aa8f4a34a8b33f5d862 - RTEMS tools: 10.2.1 20210309 (RTEMS 6, RSB 5e449fb5c2cb6812a238f9f9764fd339cbbf05c2, Newlib d10d0d9) + RTEMS tools: 10.2.1 20210309 (RTEMS @rtems-ver-major@, RSB 5e449fb5c2cb6812a238f9f9764fd339cbbf05c2, Newlib d10d0d9) executing thread ID: 0x08a010001 - executing thread name: UI1 + executing thread name: UI1 cpu 0 in error mode (tt = 0x101) 158479 0200d500: 91d02000 ta 0x0 Run time : 0:00:00.259136 diff --git a/user/start/bsp-build.rst b/user/start/bsp-build.rst index 6ffe9b0..8401d71 100644 --- a/user/start/bsp-build.rst +++ b/user/start/bsp-build.rst @@ -45,23 +45,23 @@ To build the BSP with all the tests run this command: cd $HOME/quick-start/src/rsb/rtems ../source-builder/sb-set-builder --prefix=$HOME/quick-start/rtems/5 \ - --target=sparc-rtems5 --with-rtems-bsp=erc32 --with-rtems-tests=yes 5/rtems-kernel + --target=sparc-rtems@rtems-ver-major@ --with-rtems-bsp=erc32 --with-rtems-tests=yes @rtems-ver-major@/rtems-kernel -This command should output something like this: +This command should output something like: .. code-block:: none - RTEMS Source Builder - Set Builder, 5.1.0 - Build Set: 5/rtems-kernel - config: tools/rtems-kernel-5.cfg - package: sparc-rtems5-kernel-erc32-1 - building: sparc-rtems5-kernel-erc32-1 - sizes: sparc-rtems5-kernel-erc32-1: 2.279GB (installed: 44.612MB) - cleaning: sparc-rtems5-kernel-erc32-1 - reporting: tools/rtems-kernel-5.cfg -> sparc-rtems5-kernel-erc32-1.txt - reporting: tools/rtems-kernel-5.cfg -> sparc-rtems5-kernel-erc32-1.xml - installing: sparc-rtems5-kernel-erc32-1 -> $BASE/ - cleaning: sparc-rtems5-kernel-erc32-1 + 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: @@ -112,13 +112,13 @@ directory to your ``$PATH`` throughout the remaining steps. Run the command: .. code-block:: none - export PATH=$HOME/quick-start/rtems/6/bin:"$PATH" + export PATH=$HOME/quick-start/rtems/@rtems-ver-major@/bin:"$PATH" Check your installed tools can be found by running: .. code-block:: none - command -v sparc-rtems6-gcc && echo "found" || echo "not found" + command -v sparc-rtems@rtems-ver-major@-gcc && echo "found" || echo "not found" The output should be: @@ -128,9 +128,10 @@ The output should be: 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/6/bin` manually and if :file:`sparc-rtems6-gcc` -is present the path is wrong. If the file cannot be found return to -:ref:`QuickStartTools` and install the tools again. +: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 first step is to configure the BSP. There are various BSP build configuration options available. Some options are BSP-specific. Each section @@ -145,7 +146,7 @@ everything else. For detailed information about the BSP build system, see cd $HOME/quick-start/src/rtems echo "[sparc/erc32]" > config.ini echo "BUILD_TESTS = True" >> config.ini - ./waf configure --prefix=$HOME/quick-start/rtems/6 + ./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 @@ -154,28 +155,28 @@ 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-rtems6-gcc' : $BASE/quick-start/rtems/6/bin/sparc-rtems6-gcc - Checking for program 'sparc-rtems6-g++' : $BASE/quick-start/rtems/6/bin/sparc-rtems6-g++ - Checking for program 'sparc-rtems6-ar' : $BASE/quick-start/rtems/6/bin/sparc-rtems6-ar - Checking for program 'sparc-rtems6-ld' : $BASE/quick-start/rtems/6/bin/sparc-rtems6-ld - Checking for program 'ar' : $BASE/quick-start/rtems/6/bin/sparc-rtems6-ar - Checking for program 'g++, c++' : $BASE/quick-start/rtems/6/bin/sparc-rtems6-g++ - Checking for program 'ar' : $BASE/quick-start/rtems/6/bin/sparc-rtems6-ar - Checking for program 'gas, gcc' : $BASE/quick-start/rtems/6/bin/sparc-rtems6-gcc - Checking for program 'ar' : $BASE/quick-start/rtems/6/bin/sparc-rtems6-ar - Checking for program 'gcc, cc' : $BASE/quick-start/rtems/6/bin/sparc-rtems6-gcc - Checking for program 'ar' : $BASE/quick-start/rtems/6/bin/sparc-rtems6-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/6/bin/rtems-bin2c - Checking for program 'gzip' : /usr/bin/gzip - Checking for program 'rtems-ld' : $BASE/quick-start/rtems/6/bin/rtems-ld - Checking for program 'rtems-syms' : $BASE/quick-start/rtems/6/bin/rtems-syms - Checking for program 'xz' : $BASE/anaconda3/bin/xz + 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 second step. @@ -219,12 +220,12 @@ by ``$BASE``. 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/6/sparc-rtems6/erc32/lib/include/libchip/am29lv160.h (from bsps/include/libchip/am29lv160.h) - + install $BASE/quick-start/rtems/6/sparc-rtems6/erc32/lib/include/libchip/mc146818a.h (from bsps/include/libchip/mc146818a.h) - + install $BASE/quick-start/rtems/6/sparc-rtems6/erc32/lib/include/libchip/mc68681.h (from bsps/include/libchip/mc68681.h)) + + 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)) ... - + install $BASE/quick-start/rtems/6/sparc-rtems6/erc32/lib/include/rtems/score/watchdogticks.h (from cpukit/include/rtems/score/watchdogticks.h) - + install $BASE/quick-start/rtems/6/sparc-rtems6/erc32/lib/include/rtems/score/wkspace.h (from cpukit/include/rtems/score/wkspace.h) - + install $BASE/quick-start/rtems/6/sparc-rtems6/erc32/lib/include/rtems/score/wkspacedata.h (from cpukit/include/rtems/score/wkspacedata.h) + + 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)) -- cgit v1.2.3