[PATCH] user/gsoc: GSoC Getting Started Instructions
Niteesh G. S.
niteesh.gs at gmail.com
Mon Mar 23 05:59:41 UTC 2020
On Mon, Mar 23, 2020 at 6:43 AM Chris Johns <chrisj at rtems.org> wrote:
> On 2020-03-18 07:36, G S Niteesh Babu wrote:
> > ---
> > 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,
>
> This should reference the Host section and ask the student to select one
> of the supported hosts. Recommending a Unix host is fine.
>
> > which could be in a
> > +virtual machine, for example that uses `Virtualbox <
> https://www.virtualbox.org/>`_
>
> This is fine.
>
> > +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.
>
> For some people Unix is more difficult.
>
> > +
> > +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
> > +-------------------------------
>
> From here on I would prefer references to the existing documentation
> with any GSoC details list here. I would prefer we avoid duplicating
> prefix, sources and building anywhere in the documentaion as it will
> only confuse search engines, normal users and GSoC students. The Quick
> Start Guide has taken a long time to get to where it is. If there is
> something in the Quick Start guide that needs fixing please let me know.
>
I had this discussion with Gedare. We felt it would be nice to have all the
instructions in once place instead of referencing them. It would make it
easier for newcomers and students to follow.
Maybe I'll use the same prefix as in the Quick Start guide but have all the
instructions here.
> I am sorry I have not commented before now, I have been distracked.
>
> Thanks
> Chris
>
> > +
> > +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
> >
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rtems.org/pipermail/devel/attachments/20200323/87805dca/attachment-0001.html>
More information about the devel
mailing list