[PATCH] user/gsoc: GSoC Getting Started Instructions
G S Niteesh Babu
niteesh.gs at gmail.com
Tue Mar 17 20:36:25 UTC 2020
---
user/index.rst | 1 +
user/start/gsoc.rst | 453 +++++++++++++++++++++++++++++++++++++++++++
user/start/index.rst | 1 +
3 files changed, 455 insertions(+)
create mode 100644 user/start/gsoc.rst
diff --git a/user/index.rst b/user/index.rst
index 0e644c9..f253ea6 100644
--- a/user/index.rst
+++ b/user/index.rst
@@ -10,6 +10,7 @@ RTEMS User Manual (|version|).
.. topic:: Copyrights and License
+ | |copy| 2020 Niteesh Babu
| |copy| 2019 Vijay Kumar Banerjee
| |copy| 2018 Amaan Cheval
| |copy| 2018 Marçal Comajoan Cara
diff --git a/user/start/gsoc.rst b/user/start/gsoc.rst
new file mode 100644
index 0000000..071c1cc
--- /dev/null
+++ b/user/start/gsoc.rst
@@ -0,0 +1,453 @@
+.. comment: SPDX-License-Identifier: CC-BY-SA-4.0
+
+.. comment: Copyright (C) 2020 Niteesh Babu <niteesh.gs at gmail.com>
+.. comment: All rights reserved.
+
+
+.. _QuickStartGSoC:
+
+GSoC Getting Started
+====================
+
+The goal of this page is to help you get RTEMS compiled and running so you can
+start with the real work.
+
+Please join the :r:list:`users` and :r:list:`devel` mailing lists and ask questions.
+Help correct any deficiencies in the code or documentation you spot, including
+those on the wiki. The ultimate goal of GSoC is to help you become part of the
+open source community.
+
+.. _QuickStartConfigureComputer:
+
+Configure a Development Computer
+--------------------------------
+
+You will be best served by using a GNU/Linux environment, which could be in a
+virtual machine, for example that uses `Virtualbox <https://www.virtualbox.org/>`_
+and should run on most modern desktop systems. You should also be able to work
+with a MacOS or Windows system, but might encounter more difficulty than a *nix
+environment.
+
+Feel free to ask questions on the rtems-users mailing list in case you face
+trouble with the steps. If you want tools for another architecture, replace
+sparc in the RSB directions with another architecture, such as arm or mips. You
+can also use the RSB to build RTEMS directly, but we recommend that you learn
+how to build RTEMS by itself with the compiler tools generated by RSB.
+
+As you will be compiling a lot of code, it is recommended to have a reasonably
+fast development machine.
+
+The instructions in this chapter will help you in quickly setting up a
+development environment. For a detailed set of instruction please refer to the
+:ref:`QuickStart` chapter.
+
+You need tools for your host’s operating system to build the RTEMS tool suite
+from source. Please have a look at the :ref:`host-computer` chapter for the
+instructions to install the tools.
+
+Choosing an Installation Prefix
+-------------------------------
+
+The term ``prefix`` refers to the path on your computer where the software is to
+be installed.
+In this case, we choose the home directory ``$HOME/rtems`` as our prefix.
+
+.. code-block:: none
+
+ mkdir $HOME/rtems
+
+Getting Sources
+---------------
+
+We obtain the source code for the :ref:`RTEMS Source Builder (RSB) <RSB>` and
+RTEMS from the RTEMS :r:url:`git`.
+
+The :ref:`RTEMS Source Builder (RSB) <RSB>` is the tool used to build RTEMS
+packages from source. We will be using the RSB to build RTEMS the source.
+Please have a look at the :ref:`RTEMS Source Builder (RSB) <RSB>` for more
+information.
+
+We'll clone to the repositories to ``$HOME/rtems/src``.
+
+.. code-block:: none
+
+ mkdir -p $HOME/rtems/src
+ cd $HOME/rtems/src
+ git clone git://git.rtems.org/rtems-source-builder.git rsb
+ git clone git://git.rtems.org/rtems.git
+
+Building the Tool suite
+-----------------------
+
+Once you have cloned the repositories and installed the required tools for
+your host operating system. You can start building the tools suite for your BSP.
+The tools suite is the collection of compiler, debugger, Assembler and other
+tools required for developing the software.
+
+You can check if your host is set up correctly using ``sb-check`` tool provided
+in the RSB repository.
+
+.. code-block:: none
+
+ cd $HOME/rtems/src/rsb/source-builder
+ ./sb-check
+
+If you installed all the required tools you should have the following output.
+
+.. code-block:: none
+
+ RTEMS Source Builder - Check, 5 (0b7e87143b76)
+ Environment is ok
+
+.. note:: The numbers may vary depending on the RSB release.
+
+The tool suite for RTEMS and the RTEMS sources are tightly coupled. For example,
+do not use a RTEMS version 5 tool suite with RTEMS version 4.11 sources and vice
+versa. In simple words, make sure you clone both the repositories at the same
+time.
+
+The tools suite is architecture specific. In this guide we will be building the
+tools suite for the SPARC architecture. So the tool suite name is sparc-rtems5.
+You can build the tools suite for other architectures like ARM, RISCV by
+replacing the architecture name. For example, for ARM the tools suite name would
+be arm-rtems5.
+
+The following command builds and installs the tools suite in the path mentioned
+in the prefix option.
+
+.. code-block:: none
+
+ cd $HOME/rtems/src/rsb/rtems
+ ../source-builder/sb-set-builder --prefix=$HOME/rtems/5 5/rtems-sparc
+
+This command should output something like this (omitted lines are denoted by …).
+The build host appears as part of the name of the package being built. The name
+you see may vary depending on the host you are using:
+
+.. code-block:: none
+
+ RTEMS Source Builder - Set Builder, 5.1.0
+ Build Set: 5/rtems-sparc
+ ...
+ config: tools/rtems-binutils-2.34.cfg
+ package: sparc-rtems5-binutils-2.34-x86_64-freebsd12.1-1
+ building: sparc-rtems5-binutils-2.34-x86_64-freebsd12.1-1
+ sizes: sparc-rtems5-binutils-2.34-x86_64-freebsd12.1-1: 305.866MB (installed: 29.966MB)
+ cleaning: sparc-rtems5-binutils-2.34-x86_64-freebsd12.1-1
+ reporting: tools/rtems-binutils-2.34.cfg -> sparc-rtems5-binutils-2.34-x86_64-freebsd12.1-1.txt
+ reporting: tools/rtems-binutils-2.34.cfg -> sparc-rtems5-binutils-2.34-x86_64-freebsd12.1-1.xml
+ config: tools/rtems-gcc-7.5.0-newlib-fbaa096.cfg
+ package: sparc-rtems5-gcc-7.5.0-newlib-fbaa096-x86_64-freebsd12.1-1
+ building: sparc-rtems5-gcc-7.5.0-newlib-fbaa096-x86_64-freebsd12.1-1
+ ....
+ Build Sizes: usage: 5.684GB total: 1.112GB (sources: 143.803MB, patches: 21.348KB, installed 995.188MB)
+ Build Set: Time 0:21:35.626294
+
+Once the build has successfully completed you can check if the cross C compiler
+works with the following command:
+
+.. code-block:: none
+
+ $HOME/rtems/5/bin/sparc-rtems5-gcc --version
+
+This command should output something like below. The version information helps
+you to identify the exact sources used to build the cross compiler of your RTEMS
+tool suite.
+
+.. code-block:: none
+
+ sparc-rtems5-gcc (GCC) 7.5.0 20191114 (RTEMS 5, RSB 5.1.0, Newlib fbaa096)
+ Copyright (C) 2017 Free Software Foundation, Inc.
+ This is free software; see the source for copying conditions. There is NO
+ warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+
+Add the tools suite to your ``$PATH`` by the following command:
+
+.. code-block:: none
+
+ export PATH=$HOME/rtems/5:"$PATH"
+
+This is only valid for the current terminal session. To make it permanant, add
+it your ``~/.profile`` by the following command:
+
+.. code-block:: none
+
+ echo "export PATH=$PATH:$HOME/rtems/5" >> ~/.profile
+
+Bootstrap the RTEMS Source
+--------------------------
+
+Since you have built and installed the tools required for compilation of RTEMS.
+It is time to build the BSP. But before that it is necessary to bootstrap the
+the build system in the RTEMS source. Bootstrap is the process where the files
+required for building RTEMS are generated. This process is required because
+RTEMS does not keep the generated files under version control.
+
+To perform bootstrap we need to enter the cloned source directory then run the
+bootstrap commands:
+
+.. code-block:: none
+
+ cd $HOME/rtems/src/rtems
+ ./bootstrap -c && /$HOME/rtems/src/rtems/rtems-bootstrap
+
+Build the BSP
+-------------
+
+The Board Support Package (BSP) is the software that glues a specific board or
+hardware to RTEMS. For information on available BSPs you can refer to :ref:`BSPs`.
+
+We will be building the SPARC ERC32 BSP since we have installed the SPARC tools
+suite and also because this BSP has a robust simulator that runs the example and
+test executables on your host computer.
+
+The RSB can also be used to build the BSP. But we will be building it manually.
+You can refer to the :ref:`QuickStart` chapter for instructions on building it
+using RSB.
+
+We by choosing a build directory. It must be separate from the RTEMS source
+directory. We will be using ``$HOME/rtems/build/erc32`` as our build directory.
+
+.. code-block:: none
+
+ mkdir -p $HOME/rtems/build/erc32
+
+We now configure the BSP. We enable all the tests. But if you want you can
+enable only a part of the tests by replacing `--enable-tests` with
+`--enable-tests=samples`. This would only build the tests under
+``$HOME/rtems/src/rtems/testsuites/samples`` and will also reduce your build
+times significantly.
+
+.. code-block:: none
+
+ cd $HOME/rtems/build/erc32
+ $HOME/rtems/src/rtems/configure \
+ --prefix=$HOME/quick-start/rtems/5 \
+ --enable-maintainer-mode \
+ --target=sparc-rtems5 \
+ --enable-rtemsbsp=erc32 \
+ --enable-tests
+
+This command should output something like this (omitted lines are denoted by ...):
+
+.. code-block:: none
+
+ checking for gmake... gmake
+ checking for RTEMS Version... 5.0.0
+ checking build system type... x86_64-unknown-freebsd12.0
+ checking host system type... x86_64-unknown-freebsd12.0
+ checking target system type... sparc-unknown-rtems5
+ ...
+ config.status: creating Makefile
+
+ target architecture: sparc.
+ available BSPs: erc32.
+ 'gmake all' will build the following BSPs: erc32.
+ other BSPs can be built with 'gmake RTEMS_BSP="bsp1 bsp2 ..."'
+
+ config.status: creating Makefile
+
+The configure command will the create the Makefile required to build the BSP.
+
+We can now finally build the BSP using make.
+
+.. code-block:: none
+
+ cd $HOME/rtems/build/erc32
+ make
+
+This command should output something like this (omitted lines are denoted by …).
+
+.. code-block::none
+
+ Configuring RTEMS_BSP=erc32
+ checking for gmake... gmake
+ checking build system type... x86_64-unknown-freebsd12.0
+ checking host system type... sparc-unknown-rtems5
+ checking rtems target cpu... sparc
+ checking for a BSD-compatible install... /usr/bin/install -c
+ checking whether build environment is sane... yes
+ checking for sparc-rtems5-strip... sparc-rtems5-strip
+ checking for a thread-safe mkdir -p... $BASE/src/rtems/c/src/../../install-sh -c -d
+ checking for gawk... no
+ checking for mawk... no
+ checking for nawk... nawk
+ checking whether gmake sets $(MAKE)... yes
+ checking whether to enable maintainer-specific portions of Makefiles... yes
+ checking for RTEMS_BSP... erc32
+ checking whether CPU supports libposix... yes
+ configure: setting up make/custom
+ configure: creating make/erc32.cache
+ gmake[3]: Entering directory '$BASE/build/b-erc32/sparc-rtems5/c/erc32'
+ ...
+ sparc-rtems5-gcc -mcpu=cypress -O2 -g -ffunction-sections -fdata-sections -Wall -Wmissing-prototypes -Wimplicit-function-declaration -Wstrict-prototypes -Wnested-externs -B./../../lib/libbsp/sparc/erc32 -B$BASE/src/rtems/bsps/sparc/erc32/start -specs bsp_specs -qrtems -L./../../cpukit -L$BASE/src/rtems/bsps/sparc/shared/start -Wl,--wrap=printf -Wl,--wrap=puts -Wl,--wrap=putchar -Wl,--gc-sections -o spwkspace.exe spwkspace/spwkspace-init.o ./../../lib/libbsp/sparc/erc32/librtemsbsp.a ./../../cpukit/librtemscpu.a
+ gmake[5]: Leaving directory '$BASE/build/b-erc32/sparc-rtems5/c/erc32/testsuites/sptests'
+ gmake[4]: Leaving directory '$BASE/build/b-erc32/sparc-rtems5/c/erc32/testsuites'
+ gmake[3]: Leaving directory '$BASE/build/b-erc32/sparc-rtems5/c/erc32'
+ gmake[2]: Leaving directory '$BASE/build/b-erc32/sparc-rtems5/c/erc32'
+ gmake[1]: Leaving directory '$BASE/build/b-erc32/sparc-rtems5/c'
+ gmake[1]: Entering directory '$BASE/build/b-erc32'
+ gmake[1]: Nothing to be done for 'all-am'.
+ gmake[1]: Leaving directory '$BASE/build/b-erc32'
+
+The last step is installing the BSP.
+
+.. code-block:: none
+
+ cd $HOME/rtems/build/erc32
+ make install
+
+This command should output something like this (omitted lines are denoted by …).
+In this output the base directory $HOME/rtems was replaced by $BASE.
+
+.. code-block:: none
+
+ Making install in sparc-rtems5/c
+ gmake[1]: Entering directory '$BASE/build/b-erc32/sparc-rtems5/c'
+ Making install in .
+ gmake[2]: Entering directory '$BASE/build/b-erc32/sparc-rtems5/c'
+ gmake[3]: Entering directory '$BASE/build/b-erc32/sparc-rtems5/c'
+ gmake[3]: Nothing to be done for 'install-exec-am'.
+ gmake[3]: Nothing to be done for 'install-data-am'.
+ gmake[3]: Leaving directory '$BASE/build/b-erc32/sparc-rtems5/c'
+ gmake[2]: Leaving directory '$BASE/build/b-erc32/sparc-rtems5/c'
+ Making install in erc32
+ gmake[2]: Entering directory '$BASE/build/b-erc32/sparc-rtems5/c/erc32'
+ gmake[3]: Entering directory '$BASE/build/b-erc32/sparc-rtems5/c/erc32'
+ Making install-am in .
+ Making install-am in cpukit
+ gmake[4]: Entering directory '$BASE/build/b-erc32/sparc-rtems5/c/erc32/cpukit'
+ gmake[5]: Entering directory '$BASE/build/b-erc32/sparc-rtems5/c/erc32/cpukit'
+ gmake[5]: Nothing to be done for 'install-exec-am'.
+ $BASE/src/rtems/c/src/../../cpukit/../install-sh -c -d '$BASE/rtems/5/sparc-rtems5/erc32/lib/include'
+ ...
+ $BASE/src/rtems/make/Templates/Makefile.lib '$BASE/rtems/5/share/rtems5/make/Templates'
+ $BASE/src/rtems/./install-sh -c -d '$BASE/rtems/5/make/custom'
+ /usr/bin/install -c -m 644 $BASE/src/rtems/make/custom/default.cfg '$BASE/rtems/5/make/custom'
+ gmake[2]: Leaving directory '$BASE/build/b-erc32'
+ gmake[1]: Leaving directory '$BASE/build/b-erc32'
+
+Testing the BSP
+---------------
+
+Since, we now have a BSP built and installed. We will test it by running a
+Hello world example. This example is already been built during the BSP build
+phase.
+
+We can run this using the simulator provided by RSB tools suite. The SPARC tools
+suite comes with SIS simulator which can we used to run your executables on your
+host computer without the need for hardware.
+
+The ``Hello World`` executable can be found under
+``$HOME/rtems/build/erc32/sparc-rtems5/c/erc32/testsuites/samples/hello/hello.exe``.
+
+To run the executable in the simulator we use the following command:
+
+.. code-block:: none
+
+ sparc-rtems5-sis sparc-rtems5/c/erc32/testsuites/samples/hello/hello.exe
+
+The output will be the following:
+
+.. code-block:: none
+
+ sparc-rtems5-sis sparc-rtems5/c/erc32/testsuites/samples/hello/hello.exe
+ SIS - SPARC/RISCV instruction simulator 2.20, copyright Jiri Gaisler 2019
+ Bug-reports to jiri at gaisler.se
+ ERC32 emulation enabled
+
+ Loaded sparc-rtems5/c/erc32/testsuites/samples/hello.exe, entry 0x02000000
+
+ sis>
+
+This command will start the simulator and will load the executable in it. To run
+the exe, enter run in the simulator prompt ( `sis>` ). This will running the
+executable in the simulator and the following output will be produced.
+
+.. code-block:: none
+
+ sparc-rtems5-sis sparc-rtems5/c/erc32/testsuites/samples/hello/hello.exe
+ SIS - SPARC/RISCV instruction simulator 2.20, copyright Jiri Gaisler 2019
+ Bug-reports to jiri at gaisler.se
+ ERC32 emulation enabled
+
+ Loaded sparc-rtems5/c/erc32/testsuites/samples/hello.exe, entry 0x02000000
+
+ sis> run
+
+
+ *** BEGIN OF TEST HELLO WORLD ***
+ *** TEST VERSION: 5.0.0.c6d8589bb00a9d2a5a094c68c90290df1dc44807
+ *** TEST STATE: EXPECTED-PASS
+ *** TEST BUILD: RTEMS_POSIX_API
+ *** TEST TOOLS: 7.5.0 20191114 (RTEMS 5, RSB 83fa79314dd87c0a8c78fd642b2cea3138be8dd6, Newlib 3e24fbf6f)
+ Hello World
+
+ *** END OF TEST HELLO WORLD ***
+
+
+ *** FATAL ***
+ fatal source: 0 (INTERNAL_ERROR_CORE)
+ fatal code: 5 (INTERNAL_ERROR_THREAD_EXITTED)
+ RTEMS version: 5.0.0.c6d8589bb00a9d2a5a094c68c90290df1dc44807
+ RTEMS tools: 7.5.0 20191114 (RTEMS 5, RSB 83fa79314dd87c0a8c78fd642b2cea3138be8dd6, Newlib 3e24fbf6f)
+ executing thread ID: 0x08a010001
+ executing thread name: UI1
+ cpu 0 in error mode (tt = 0x101)
+ 116401 02009ae0: 91d02000 ta 0x0
+
+Prove You Can Work On RTEMS
+---------------------------
+
+Modify the hello world example to include a new different print statement.
+Something like "Hello from The Dark Side!". Then send us enough to prove to us
+that you did this. We want to know you can work with RTEMS.
+
+Create a patch of your changes and send it to :r:link:`devel` along with the
+screenshot of the output.
+
+If you followed this guide, this hello world modification will likely need to be
+made to the file you'll have in ``$HOME/rtems/src/rtems/testsuites/samples/hello/init.c``.
+You can edit the file, commit your changes using git, and then run git
+format-patch master to generate a patch file.
+
+Creating Patch
+--------------
+
+Once you have made the required changes in the ``init.c`` file. You will have to
+commit those changes. Before commiting the changes make sure you are not on the
+master branch. This is to avoid merge conflicts. You can create and work on a
+separate local branch with the following git command.
+
+.. code-block:: none
+
+ cd $HOME/rtems/src/rtems
+ git checkout -b gsoc
+
+This is will create a separate branch called `gsoc` and will switch you to it.
+
+Stage the file and commit using the following commands.
+
+.. code-block:: none
+
+ git add $HOME/rtems/src/rtems/testsuites/samples/hello/init.c
+ git commit -m "<YOUR-COMMIT-MESSAGE>"
+
+You can now create a patch file using ``git format-patch``.
+
+.. code-block:: none
+
+ git format-patch -1
+
+Sending Patches
+---------------
+
+Once the patch file is created. You can now send it to :r:link:`devel` using
+``git send-email``. Please refer to `git send-email <https://git-scm.com/docs/git-send-email>`_
+for instructions on seting up the SMTP server and other options.
+
+The following command will send the patch to the mailing list.
+
+.. code-block:: none
+
+ git send-email <YOUR-PATCH-FILE> --to devel at rtems.org
diff --git a/user/start/index.rst b/user/start/index.rst
index d6333f3..2d3ab2c 100644
--- a/user/start/index.rst
+++ b/user/start/index.rst
@@ -22,3 +22,4 @@ applications on top of RTEMS.
bsp-build
bsp-test
app
+ gsoc
--
2.17.1
More information about the devel
mailing list