rtems/rtems-libbsd
1
0
Fork 0
mirror of https://git.rtems.org/rtems-libbsd/ synced 2025-10-14 07:15:58 +08:00
Code Issues Packages Projects Releases Wiki Activity

Convert *.md files to reST

Browse Source 
The reST format is used by the standard RTEMS documentation.
This commit is contained in:
Sebastian Huber
2022-05-19 12:58:20 +02:00
parent 765a0b73c0
commit 30e2b2867c
3 changed files with 485 additions and 468 deletions
Download Patch File Download Diff File Expand all files Collapse all files

374
CONTRIBUTING.md → CONTRIBUTING.rst
View File

@@ -1,8 +1,8 @@
Guidelines for Developing and Contributing Code
===============================================
***********************************************
Introduction
------------
============
This guide aims to help developing and contributing code to the libbsd. One
goal of the libbsd is to stay in synchronization with FreeBSD. This is only
@@ -10,31 +10,31 @@ feasible if certain rules are in place. Otherwise, managing more than a
thousand imported source files will become too labour intensive eventually.
What is in the Git Repository
-----------------------------
=============================
The libbsd a self-contained kit with FreeBSD and RTEMS components
pre-merged. The Waf wscript in libbsd automatically generates the build when
you run waf by reading the modules and module's source, header, defines and
special flags from `libbsd.py`. This is the same module data used to manage
special flags from ``libbsd.py``. This is the same module data used to manage
the FreeBSD source.
Any changes to source in the `freebsd` directories will need to be merged
upstream into our master FreeBSD checkout, the `freebsd-org` submodule.
Any changes to source in the ``freebsd`` directories will need to be merged
upstream into our master FreeBSD checkout, the ``freebsd-org`` submodule.
The repository contains two FreeBSD source trees. In the `freebsd` directory
The repository contains two FreeBSD source trees. In the ``freebsd`` directory
are the so called *managed* FreeBSD sources used to build the BSD library.
The FreeBSD source in `freebsd-org` is the *master* version. The
`freebsd-to-rtems.py` script is used to transfer files between the two trees
using the module defnitions in `libbsd.py`. In general terms, if you have
The FreeBSD source in ``freebsd-org`` is the *master* version. The
``freebsd-to-rtems.py`` script is used to transfer files between the two trees
using the module defnitions in ``libbsd.py``. In general terms, if you have
modified managed FreeBSD sources, you will need to run the script in *revert*
or *reverse* mode using the `-R` switch. This will copy the source back to
your local copy of the master FreeBSD source so you can run `git diff` against
or *reverse* mode using the ``-R`` switch. This will copy the source back to
your local copy of the master FreeBSD source so you can run ``git diff`` against
the upstream FreeBSD source. If you want to transfer source files from the
master FreeBSD source to the manged FreeBSD sources, then you must run the
script in *forward* mode (the default).
Kernel and User Space
---------------------
=====================
FreeBSD uses virtual memory to run separate address spaces. The kernel is one
address space and each process the kernel runs is another separate address
@@ -44,8 +44,8 @@ linked executable for the kernel and user land maintains the separation.
RTEMS is a single address space operating system and that means the kernel and
user space code have to be linked to together and be able to run side by
side. This creates additional complexity when working with the FreeBSD code,
for example the FreeBSD kernel has a `malloc` call with a different signature
to the user land `malloc` call. The RTEMS LibBSD support code provides
for example the FreeBSD kernel has a ``malloc`` call with a different signature
to the user land ``malloc`` call. The RTEMS LibBSD support code provides
structured ways to manage the separation.
LibBSD manages the integration of kernel and user code by knowing the context
@@ -55,52 +55,52 @@ include paths a source file sees. The kernel code sees the kernel, CPU
specific and build system generated include paths in that order. User code
sees the user include paths then the kernel, CPU specific and build system
generated include paths in that order. The FreeBSD OS include path
`/usr/include` has a mix of kernel and user space header files. The kernel
``/usr/include`` has a mix of kernel and user space header files. The kernel
headers let user space code cleanly access structures the kernel exports. If a
user header file has the same name as a kernel header file the user file will
be used in the user code rather than the kernel file. If the user code
includes a kernel header that file will be found and included.
Organization
------------
============
The top level directory contains a few directories and files. The following
are important to understand
* `freebsd-to-rtems.py` - script to convert to and free FreeBSD and RTEMS trees,
* `create-kernel-namespace.sh` - script to create the kernel namespace header `<machine/rtems-bsd-kernel-namespace.h>`,
* `wscript` - automatically generates the build from libbsd.py,
* `libbsd.py` - modules, sources, compile flags, and dependencies
* `freebsd/` - from FreeBSD by script,
* `rtemsbsd/` - RTEMS specific implementations of FreeBSD kernel support routines,
* `testsuite/` - RTEMS specific tests, and
* `libbsd.txt` - documentation in Asciidoc.
* ``freebsd-to-rtems.py`` - script to convert to and free FreeBSD and RTEMS trees,
* ``create-kernel-namespace.sh`` - script to create the kernel namespace header ``<machine/rtems-bsd-kernel-namespace.h>``,
* ``wscript`` - automatically generates the build from libbsd.py,
* ``libbsd.py`` - modules, sources, compile flags, and dependencies
* ``freebsd/`` - from FreeBSD by script,
* ``rtemsbsd/`` - RTEMS specific implementations of FreeBSD kernel support routines,
* ``testsuite/`` - RTEMS specific tests, and
* ``libbsd.txt`` - documentation in Asciidoc.
Moving Code Between Managed and Master FreeBSD Source
-----------------------------------------------------
=====================================================
The script `freebsd-to-rtems.py` is used to copy code from FreeBSD to the
The script ``freebsd-to-rtems.py`` is used to copy code from FreeBSD to the
rtems-libbsd tree and to reverse this process. This script attempts to
automate this process as much as possible and performs some transformations
on the FreeBSD code. Its command line arguments are shown below:
```
freebsd-to-rtems.py [args]
-?|-h|--help print this and exit
-d|--dry-run run program but no modifications
-D|--diff provide diff of files between trees
-e|--early-exit evaluate arguments, print results, and exit
-m|--makefile Warning: depreciated and will be removed
-b|--buildscripts just generate the build scripts
-S|--stats Print a statistics report
-R|--reverse default FreeBSD -> RTEMS, reverse that
-r|--rtems RTEMS Libbsd directory (default: '.')
-f|--freebsd FreeBSD SVN directory (default: 'freebsd-org')
-c|--config Output the configuration then exit
-v|--verbose enable verbose output mode
```
.. code-block:: none
In its default mode of operation, `freebsd-to-rtems.py` is used to copy code
freebsd-to-rtems.py [args]
-?|-h|--help print this and exit
-d|--dry-run run program but no modifications
-D|--diff provide diff of files between trees
-e|--early-exit evaluate arguments, print results, and exit
-m|--makefile Warning: depreciated and will be removed
-b|--buildscripts just generate the build scripts
-S|--stats Print a statistics report
-R|--reverse default FreeBSD -> RTEMS, reverse that
-r|--rtems RTEMS Libbsd directory (default: '.')
-f|--freebsd FreeBSD SVN directory (default: 'freebsd-org')
-c|--config Output the configuration then exit
-v|--verbose enable verbose output mode
In its default mode of operation, ``freebsd-to-rtems.py`` is used to copy code
from FreeBSD to the rtems-libbsd tree and perform transformations.
In *reverse mode*, this script undoes those transformations and copies
@@ -127,18 +127,18 @@ those files into the RTEMS FreeBSD tree.
The following is an example forward run with no changes.
```
$ ./freebsd-to-rtems.py -v
Verbose: yes (1)
Dry Run: no
Diff Mode Enabled: no
Only Generate Build Scripts: no
RTEMS Libbsd Directory: .
FreeBSD SVN Directory: freebsd-org
Direction: forward
Forward from FreeBSD GIT into .
0 file(s) were changed:
```
.. code-block:: none
$ ./freebsd-to-rtems.py -v
Verbose: yes (1)
Dry Run: no
Diff Mode Enabled: no
Only Generate Build Scripts: no
RTEMS Libbsd Directory: .
FreeBSD SVN Directory: freebsd-org
Direction: forward
Forward from FreeBSD GIT into .
0 file(s) were changed:
The script may also be used to generate a diff in either forward or reverse
direction.
@@ -147,47 +147,49 @@ You can add more than one verbose option (-v) to the command line and get more
detail and debug level information from the command.
FreeBSD Baseline
----------------
================
Use
```
$ git log freebsd-org
```
.. code-block:: none
$ git log freebsd-org
to figure out the current FreeBSD baseline.
How to Import Code from FreeBSD
-------------------------------
===============================
* In case you import files from a special FreeBSD version, then update the list above.
* Run `git status` and make sure your working directory is clean.
* Run `./freebsd-to-rtems.py -R`
* Run `./freebsd-to-rtems.py`
* Run `git status` and make sure your working directory is clean. If you see modified files, then the `freebsd-to-rtems.py` script needs to be fixed first.
* Add the files to import to `libbsd.py` and your intended build set (for example `buildset/default.ini`.
* Run `./freebsd-to-rtems.py`
* Immediately check in the imported files without the changes to `libbsd.py` and the buildsets. Do not touch the imported files yourself at this point.
* Run ``git status`` and make sure your working directory is clean.
* Run ``./freebsd-to-rtems.py -R``
* Run ``./freebsd-to-rtems.py``
* Run ``git status`` and make sure your working directory is clean. If you see modified files, then the ``freebsd-to-rtems.py`` script needs to be fixed first.
* Add the files to import to ``libbsd.py`` and your intended build set (for example ``buildset/default.ini``.
* Run ``./freebsd-to-rtems.py``
* Immediately check in the imported files without the changes to ``libbsd.py`` and the buildsets. Do not touch the imported files yourself at this point.
* Port the imported files to RTEMS. See 'Rules for Modifying FreeBSD Source'.
* Add a test to the testsuite if possible.
* Run `./create-kernel-namespace.sh` if you imported kernel space headers. Add only your new defines via `git add -p rtemsbsd/include/machine/rtems-bsd-kernel-namespace.h`.
* Run ``./create-kernel-namespace.sh`` if you imported kernel space headers. Add only your new defines via ``git add -p rtemsbsd/include/machine/rtems-bsd-kernel-namespace.h``.
* Create one commit from this.
The -S or --stats option generates reports the changes we have made to
FreeBSD. If the code has been reserved into the original FreeBSD tree it will
show nothing has changed. To see what we have change:
```
$ cd freebsd-org
$ git checkout -- .
$ cd ..
$ ./freebsd-to-rtems.py -R -S -d
```
.. code-block:: none
$ cd freebsd-org
$ git checkout -- .
$ cd ..
$ ./freebsd-to-rtems.py -R -S -d
The report lists the files change based on the opacity level. The opacity is a
measure on how much of a file differs from the original FreeBSD source. The
lower the value the more transparent the source file it.
Porting of User-Space Utilities
------------------------------
===============================
The theory behind the described method is to put all BSS and initialized data
objects into a named section. This section then will be saved before the code is
@@ -196,157 +198,165 @@ threaded execution of the application but minimizes the necessary changes to the
original FreeBSD code.
* Import and commit the unchanged source files like described above.
* Add the files to the [libbsd.py](libbsd.py) and build them.
* Add the files to the `<libbsd.py>`_ and build them.
* Check the sources for everything that can be made const. This type of patches
should go back to the upstream FreeBSD sources.
* Move static variables out of functions if necessary (search for
"\tstatic"). These patches most likely will not be accepted into FreeBSD.
* Add a rtems_bsd_command_PROGNAME() wrapper function to the source file
containing the main function (e.g. PROGNAME = pfctl). For an example look at
`rtems_bsd_command_pfctl()` in [pfctl.c](freebsd/sbin/pfctl/pfctl.c).
``rtems_bsd_command_pfctl()`` in `pfctl.c <freebsd/sbin/pfctl/pfctl.c>`_.
* You probably have to use getopt_r() instead of getopt(). Have a look at
[pfctl.c](freebsd/sbin/pfctl/pfctl.c).
`pfctl.c <freebsd/sbin/pfctl/pfctl.c>`_.
* Build the libbsd without optimization.
* Use the `userspace-header-gen.py` to generate some necessary header
files. It will generate one `rtems-bsd-PROGNAME-MODULE-data.h` per object file, one
`rtems-bsd-PROGNAME-namespace.h` and one `rtems-bsd-PROGNAME-data.h`. To call
* Use the ``userspace-header-gen.py`` to generate some necessary header
files. It will generate one ``rtems-bsd-PROGNAME-MODULE-data.h`` per object file, one
``rtems-bsd-PROGNAME-namespace.h`` and one ``rtems-bsd-PROGNAME-data.h``. To call
the script, you have to compile the objects and afterwards run the helper
script with a call similar to this one:
`python ./userspace-header-gen.py build/arm-rtems4.12-xilinx_zynq_a9_qemu/freebsd/sbin/pfctl/*.o -p pfctl`
``python ./userspace-header-gen.py build/arm-rtems4.12-xilinx_zynq_a9_qemu/freebsd/sbin/pfctl/*.o -p pfctl``
Replace the name (given via -p option) by the name of the userspace tool. It
has to match the name that is used in the RTEMS linker set further below.
`Note:` the script `userspace-header-gen.py` depends on pyelftools. It can be
``Note:`` the script ``userspace-header-gen.py`` depends on pyelftools. It can be
installed using pip:
`pip install --user pyelftools`
``pip install --user pyelftools``
* If you regenerated files that have already been generated, you may have to
remove RTEMS-specific names from the namespace. The defaults (linker set names
and rtems_bsd_program_.*) should already be filtered.
* Put the generated header files into the same folder like the source files.
* At the top of each source file place the following right after the user-space header:
```c
#ifdef __rtems__
#include <machine/rtems-bsd-program.h>
#include "rtems-bsd-PROGNAME-namespace.h"
#endif /* __rtems__ */
```
.. code-block:: c
#ifdef __rtems__
#include <machine/rtems-bsd-program.h>
#include "rtems-bsd-PROGNAME-namespace.h"
#endif /* __rtems__ */
The following command may be useful:
```
sed -i 's%#include <machine/rtems-bsd-user-space.h>%#include <machine/rtems-bsd-user-space.h>\n\n#ifdef __rtems__\n#include <machine/rtems-bsd-program.h>\n#include "rtems-bsd-PROGNAME-namespace.h"\n#endif /* __rtems__ */%' *.c
```
.. code-block:: none
sed -i 's%#include <machine/rtems-bsd-user-space.h>%#include <machine/rtems-bsd-user-space.h>\n\n#ifdef __rtems__\n#include <machine/rtems-bsd-program.h>\n#include "rtems-bsd-PROGNAME-namespace.h"\n#endif /* __rtems__ */%' *.c
* At the bottom of each source file place the follwing:
```c
#ifdef __rtems__
#include "rtems-bsd-PROGNAME-FILE-data.h"
#endif /* __rtems__ */
```
.. code-block:: c
#ifdef __rtems__
#include "rtems-bsd-PROGNAME-FILE-data.h"
#endif /* __rtems__ */
The following command may be useful:
```
for i in *.c ; do n=$(basename $i .c) ; echo -e "#ifdef __rtems__\n#include \"rtems-bsd-PROGNAME-$n-data.h\"\n#endif /* __rtems__ */" >> $i ; done
```
.. code-block:: none
for i in *.c ; do n=$(basename $i .c) ; echo -e "#ifdef __rtems__\n#include \"rtems-bsd-PROGNAME-$n-data.h\"\n#endif /* __rtems__ */" >> $i ; done
* Create one compilable commit.
Rules for Modifying FreeBSD Source
----------------------------------
==================================
Changes in FreeBSD files must be done using `__rtems__` C pre-processor guards.
Changes in FreeBSD files must be done using ``__rtems__`` C pre-processor guards.
This makes synchronization with the FreeBSD upstream easier and is very
important. Patches which do not follow these rules will be rejected. Only add
lines. If your patch contains lines starting with a `-`, then this is wrong.
Subtract code by added `#ifndef __rtems__`. For example:
lines. If your patch contains lines starting with a ``-``, then this is wrong.
Subtract code by added ``#ifndef __rtems__``. For example:
```c
/* Global variables for the kernel. */
.. code-block:: c
#ifndef __rtems__
/* 1.1 */
extern char kernelname[MAXPATHLEN];
#endif /* __rtems__ */
/* Global variables for the kernel. */
extern int tick; /* usec per tick (1000000 / hz) */
```
#ifndef __rtems__
/* 1.1 */
extern char kernelname[MAXPATHLEN];
#endif /* __rtems__ */
```c
#if defined(_KERNEL) || defined(_WANT_FILE)
#ifdef __rtems__
#include <rtems/libio_.h>
#include <sys/fcntl.h>
#endif /* __rtems__ */
/*
* Kernel descriptor table.
* One entry for each open kernel vnode and socket.
*
* Below is the list of locks that protects members in struct file.
*
* (f) protected with mtx_lock(mtx_pool_find(fp))
* (d) cdevpriv_mtx
* none not locked
*/
```
extern int tick; /* usec per tick (1000000 / hz) */
```c
extern int profprocs; /* number of process's profiling */
#ifndef __rtems__
extern volatile int ticks;
#else /* __rtems__ */
#include <rtems/score/watchdogimpl.h>
#define ticks _Watchdog_Ticks_since_boot
#endif /* __rtems__ */
.. code-block:: c
#endif /* _KERNEL */
```
#if defined(_KERNEL) || defined(_WANT_FILE)
#ifdef __rtems__
#include <rtems/libio_.h>
#include <sys/fcntl.h>
#endif /* __rtems__ */
/*
* Kernel descriptor table.
* One entry for each open kernel vnode and socket.
*
* Below is the list of locks that protects members in struct file.
*
* (f) protected with mtx_lock(mtx_pool_find(fp))
* (d) cdevpriv_mtx
* none not locked
*/
Add nothing (even blank lines) before or after the `__rtems__` guards. Always
include a `__rtems__` in the guards to make searches easy, so use
.. code-block:: c
* `#ifndef __rtems__`,
* `#ifdef __rtems__`,
* `#else /* __rtems__ */`, and
* `#endif /* __rtems__ */`.
extern int profprocs; /* number of process's profiling */
#ifndef __rtems__
extern volatile int ticks;
#else /* __rtems__ */
#include <rtems/score/watchdogimpl.h>
#define ticks _Watchdog_Ticks_since_boot
#endif /* __rtems__ */
#endif /* _KERNEL */
Add nothing (even blank lines) before or after the ``__rtems__`` guards. Always
include a ``__rtems__`` in the guards to make searches easy, so use
* ``#ifndef __rtems__``,
* ``#ifdef __rtems__``,
* ``#else /* __rtems__ */``, and
* ``#endif /* __rtems__ */``.
The guards must start at the begin of the line. Examples for wrong guards:
```c
static void
guards_must_start_at_the_begin_of_the_line(int j)
{
.. code-block:: c
/* WRONG */
#ifdef __rtems__
return (j + 1);
#else /* __rtems__ */
return (j + 2);
#endif /* __rtems__ */
}
static void
guards_must_start_at_the_begin_of_the_line(int j)
{
static void
missing_rtems_comments_in_the_guards(int j)
{
/* WRONG */
#ifdef __rtems__
return (j + 1);
#else /* __rtems__ */
return (j + 2);
#endif /* __rtems__ */
}
#ifdef __rtems__
return (j + 3);
/* WRONG */
#else
return (j + 4);
#endif
}
```
static void
missing_rtems_comments_in_the_guards(int j)
{
#ifdef __rtems__
return (j + 3);
/* WRONG */
#else
return (j + 4);
#endif
}
The FreeBSD build and configuration system uses option header files, e.g.
`#include "opt_xyz.h"` in an unmodified FreeBSD file. This include is
transformed by the import script into `#include <rtems/bsd/local/opt_xyz.h>`. Do
``#include "opt_xyz.h"`` in an unmodified FreeBSD file. This include is
transformed by the import script into ``#include <rtems/bsd/local/opt_xyz.h>``. Do
not disable option header includes via guards. Instead, add an empty option
header, e.g. `touch rtemsbsd/include/rtems/bsd/local/opt_xyz.h`.
```c
/* WRONG */
#ifndef __rtems__
#include <rtems/bsd/local/opt_xyz.h>
#endif /* __rtems__ */
```
header, e.g. ``touch rtemsbsd/include/rtems/bsd/local/opt_xyz.h``.
.. code-block:: c
/* WRONG */
#ifndef __rtems__
#include <rtems/bsd/local/opt_xyz.h>
#endif /* __rtems__ */
In general, provide empty header files and do not guard includes.
For new code use
[STYLE(9)](http://www.freebsd.org/cgi/man.cgi?query=style&apropos=0&sektion=9).
`STYLE(9) <http://www.freebsd.org/cgi/man.cgi?query=style&apropos=0&sektion=9>`_.
Do not format original FreeBSD code. Do not perform white space changes even
if you get git commit warnings. Check your editor settings so that it doesn't
@@ -355,10 +365,10 @@ end of the file. White space changes may result in conflicts during updates,
especially changes at the end of a file.
Automatically Generated FreeBSD Files
-------------------------------------
=====================================
Some source and header files are automatically generated during the FreeBSD
build process. The `Makefile.todo` file performs this manually. The should be
included in `freebsd-to-rtems.py` script some time in the future. For details,
build process. The ``Makefile.todo`` file performs this manually. The should be
included in ``freebsd-to-rtems.py`` script some time in the future. For details,
see also
[KOBJ(9)](http://www.freebsd.org/cgi/man.cgi?query=kobj&sektion=9&apropos=0).
`KOBJ(9) <http://www.freebsd.org/cgi/man.cgi?query=kobj&sektion=9&apropos=0>`_.

286
README.md
View File

@@ -1,286 +0,0 @@
RTEMS LibBSD
============
Welcome to building LibBSD for RTEMS using Waf. This package is a library
containing various parts of the FreeBSD kernel ported to RTEMS. The library
replaces the networking port of FreeBSD in the RTEMS kernel sources. This
package is designed to be updated from the FreeBSD kernel sources and contains
more than just the networking code.
To build this package you need a current RTEMS tool set for your architecture,
and a recent RTEMS kernel for your BSP installed. If you already have this, you
can skip to step 5 of the build procedure.
Building and Installing LibBSD
------------------------------
The following instructions show you how to build and install the RTEMS Tool
Suite for the `arm` target, the RTEMS kernel using the
`arm/xilinx_zynq_a9_qemu` Board Support Package (BSP), and the LibBSD for this
BSP.
The Waf build support for RTEMS requires you provide your BSP name as an
architecture and BSP pair. You must provide both or Waf will generate an error
message during the configure phase.
We will build an Xilinx Zynq Qemu BSP using the name
*arm/xilinx_zynq_a9_qemu*. You can copy and paste the shell commands below to
do this. The individual steps are explained afterwards.
```
sandbox="$PWD/sandbox"
mkdir sandbox
cd "$sandbox"
git clone git://git.rtems.org/rtems-source-builder.git
git clone git://git.rtems.org/rtems.git
git clone git://git.rtems.org/rtems-libbsd.git
cd "$sandbox"
cd rtems-source-builder/rtems
../source-builder/sb-set-builder --prefix="$sandbox/rtems/6" 6/rtems-arm
cd "$sandbox"
cd rtems
echo -e "[arm/xilinx_zynq_a9_qemu]\nRTEMS_POSIX_API = True" > config.ini
./waf configure --prefix "$sandbox/rtems/6"
./waf
./waf install
cd "$sandbox"
cd rtems-libbsd
git submodule init
git submodule update rtems_waf
./waf configure --prefix="$sandbox/rtems/6" \
--rtems-bsps=arm/xilinx_zynq_a9_qemu \
--buildset=buildset/default.ini
./waf
./waf install
../rtems/6/bin/rtems-test --rtems-bsp=xilinx_zynq_a9_qemu build
```
1. Create a sandbox directory:
```
$ sandbox="$PWD/sandbox"
$ mkdir sandbox
```
2. Clone the repositories:
```
$ cd "$sandbox"
$ git clone git://git.rtems.org/rtems-source-builder.git
$ git clone git://git.rtems.org/rtems.git
$ git clone git://git.rtems.org/rtems-libbsd.git
```
3. Build and install the tools:
```
$ cd "$sandbox"
$ cd rtems-source-builder/rtems
$ ../source-builder/sb-set-builder --prefix="$sandbox/rtems/6" 6/rtems-arm
```
4. Build and install the RTEMS Board Support Packages (BSP) you want to use:
```
$ cd "$sandbox"
$ cd rtems
$ echo -e "[arm/xilinx_zynq_a9_qemu]\nRTEMS_POSIX_API = True" > config.ini
$ ./waf configure --prefix "$sandbox/rtems/6"
$ ./waf
$ ./waf install
```
5. Populate the rtems_waf git submodule. Note, make sure you specify
'rtems_waf' or the FreeBSD kernel source will be cloned:
```
$ cd "$sandbox"
$ cd rtems-libbsd
$ git submodule init
$ git submodule update rtems_waf
```
6. Run Waf's configure with your specific settings. In this case the path to
the tools and RTEMS are provided on the command line and so do not need to
be in your path or environment [1]. You can use
'--rtems-archs=arm,sparc,i386' or
'--rtems-bsps=arm/xilinx_zynq_a9_qemu,sparc/sis,i386/pc586' to build for
more than BSP at a time. Note, you must provide the architecture and BSP as
a pair. Providing just the BSP name will fail. This call also explicitly
provides a buildset via the '--buildset=buildset/default.ini' option. If no
buildset is provided the default one (which is the same as the one provided
explicitly here) will be used. You can also provide multiple buildsets as a
coma separated list or via multiple '--buildset=x' options.
```
$ cd "$sandbox"
$ cd rtems-libbsd
$ ./waf configure --prefix="$sandbox/rtems/6" \
--rtems-bsps=arm/xilinx_zynq_a9_qemu \
--buildset=buildset/default.ini
```
7. Build and install. The LibBSD package will be installed into the prefix
provided to configure:
```
$ cd "$sandbox"
$ cd rtems-libbsd
$ ./waf
$ ./waf install
```
9. Run the tests:
```
$ cd "$sandbox"
$ cd rtems-libbsd
$ ../rtems/6/bin/rtems-test --rtems-bsp=xilinx_zynq_a9_qemu build
```
It is good practice to keep your environment as empty as possible. Setting
paths to tools or specific values to configure or control a build is dangerous
because settings can leak between different builds and change what you expect a
build to do. The Waf tool used here lets you specify on the command line the
tools and RTEMS paths and this is embedded in Waf's configuration information.
If you have a few source trees working at any one time with different tool sets
or configurations you can easly move between them safe in the knowledge that
one build will not infect another.
Branches
--------
* master - branch intended for the RTEMS master which tracks the FreeBSD master
branch. This branch must be used for libbsd development. Back ports to the
6-freebsd-12 are allowed.
* 6-freebsd-12 - branch intended for RTEMS 6 which tracks the FreeBSD stable/12
branch. This branch is maintained and regular updates from FreeBSD are
planned. It is recommended for production systems.
* 5-freebsd-12 - branch belongs to the RTEMS 5 release. It is based on FreeBSD
stable/12 branch. It is recommended for production systems that use RTEMS 5.
* 5 - branch belongs to the RTEMS 5 release. It is based on a FreeBSD
development version. This branch is unmaintained. Use 5-freebsd-12 for
RTEMS 5.
* freebsd-9.3 - branch for some RTEMS version with a FreeBSD 9.3 baseline.
This branch is unmaintained. It is recommended to update to RTEMS 5 or 6.
* 4.11 - branch for the RTEMS 4.11 release series. This branch is
unmaintained. It is recommended to update to RTEMS 5 or 6.
Updating RTEMS Waf Support
--------------------------
If you have a working libbsd repository and new changes to the `rtems_waf`
submodule has been made, you will need update. A `git status` will indicate
there are new commits with:
```
$ git status
[ snip output ]
modified: rtems_waf (new commits)
[ snip output ]
```
To update:
```
$ git submodule update rtems_waf
```
Please make sure you use the exact command or you might find you are cloning
the whole of the FreeBSD source tree. If that happens simply git ^C and try
again.
FreeBSD Kernel Options
----------------------
You can set FreeBSD kernel options during build configuration with the
--freebsd-option=a,b,c,... configuration command option. This is an advanced
option and should only be used if you are familiar with the internals of the
FreeBSD kernel and what these options do. Each of the comma separated options
is converted to uppercase and passed as a compiler command line define (-D).
The options are listed in:
https://github.com/freebsd/freebsd/blob/master/sys/conf/NOTES
An example to turn on a verbose kernel boot, verbose sysinit and bus debugging
configure with:
```
--freebsd-options=bootverbose,verbose_sysinit,bus_debug
```
To enable kernel internal consistency checking use:
```
--freebsd-options=invariants,invariant_support
```
SMP Requirements
----------------
In order to support
[EPOCH(9)](https://www.freebsd.org/cgi/man.cgi?query=epoch&apropos=0&sektion=9)
a scheduler with thread pinning support is required. This is the case if you
use the default scheduler configuration. EPOCH(9) is a central synchronization
mechanism of the network stack.
Qemu and Networking
-------------------
You can use the Qemu simulator to run a LibBSD based application and connect it
to a virtual network on your host. You have to create a TAP virtual Ethernet
interface for this:
```
sudo tunctl -p -t qtap -u $(whoami)
sudo ip link set dev qtap up
sudo ip addr add 169.254.1.1/16 dev qtap
```
You can show the interface state with the following command:
```
$ ip addr show qtap
27: qtap: <NO-CARRIER,BROADCAST,MULTICAST,UP> mtu 1500 qdisc pfifo_fast state DOWN group default qlen 1000
link/ether 8e:50:a2:fb:e1:3b brd ff:ff:ff:ff:ff:ff
inet 169.254.1.1/16 scope global qtap
valid_lft forever preferred_lft forever
```
You may have to assign the interface to a firewall zone.
The Qemu command line varies by board support package, here is an example for
the arm/xilinx_zynq_a9_qemu BSP:
```
qemu-system-arm -serial null -serial mon:stdio -nographic \
-M xilinx-zynq-a9 -m 256M \
-net tap,ifname=qtap,script=no,downscript=no \
-net nic,model=cadence_gem,macaddr=0e:b0:ba:5e:ba:12 \
-kernel build/arm-rtems6-xilinx_zynq_a9_qemu-default/media01.exe
```
After some seconds it will acquire a IPv4 link-local address, e.g.
```
info: cgem0: probing for an IPv4LL address
debug: cgem0: checking for 169.254.159.156
```
You can connect to the target via telnet for example:
```
$ telnet 169.254.159.156
Trying 169.254.159.156...
Connected to 169.254.159.156.
Escape character is '^]'.
RTEMS Shell on /dev/pty4. Use 'help' to list commands.
TLNT [/] #
```

293
README.rst Normal file
View File

@@ -0,0 +1,293 @@
RTEMS LibBSD
************
Welcome to building LibBSD for RTEMS using Waf. This package is a library
containing various parts of the FreeBSD kernel ported to RTEMS. The library
replaces the networking port of FreeBSD in the RTEMS kernel sources. This
package is designed to be updated from the FreeBSD kernel sources and contains
more than just the networking code.
To build this package you need a current RTEMS tool set for your architecture,
and a recent RTEMS kernel for your BSP installed. If you already have this, you
can skip to step 5 of the build procedure.
Building and Installing LibBSD
==============================
The following instructions show you how to build and install the RTEMS Tool
Suite for the ``arm`` target, the RTEMS kernel using the
``arm/xilinx_zynq_a9_qemu`` Board Support Package (BSP), and the LibBSD for this
BSP.
The Waf build support for RTEMS requires you provide your BSP name as an
architecture and BSP pair. You must provide both or Waf will generate an error
message during the configure phase.
We will build an Xilinx Zynq Qemu BSP using the name
``arm/xilinx_zynq_a9_qemu``. You can copy and paste the shell commands below to
do this. The individual steps are explained afterwards.
.. code-block:: none
sandbox="$PWD/sandbox"
mkdir sandbox
cd "$sandbox"
git clone git://git.rtems.org/rtems-source-builder.git
git clone git://git.rtems.org/rtems.git
git clone git://git.rtems.org/rtems-libbsd.git
cd "$sandbox"
cd rtems-source-builder/rtems
../source-builder/sb-set-builder --prefix="$sandbox/rtems/6" 6/rtems-arm
cd "$sandbox"
cd rtems
echo -e "[arm/xilinx_zynq_a9_qemu]\nRTEMS_POSIX_API = True" > config.ini
./waf configure --prefix "$sandbox/rtems/6"
./waf
./waf install
cd "$sandbox"
cd rtems-libbsd
git submodule init
git submodule update rtems_waf
./waf configure --prefix="$sandbox/rtems/6" \
--rtems-bsps=arm/xilinx_zynq_a9_qemu \
--buildset=buildset/default.ini
./waf
./waf install
../rtems/6/bin/rtems-test --rtems-bsp=xilinx_zynq_a9_qemu build
1. Create a sandbox directory:
.. code-block:: none
$ sandbox="$PWD/sandbox"
$ mkdir sandbox
2. Clone the repositories:
.. code-block:: none
$ cd "$sandbox"
$ git clone git://git.rtems.org/rtems-source-builder.git
$ git clone git://git.rtems.org/rtems.git
$ git clone git://git.rtems.org/rtems-libbsd.git
3. Build and install the tools:
.. code-block:: none
$ cd "$sandbox"
$ cd rtems-source-builder/rtems
$ ../source-builder/sb-set-builder --prefix="$sandbox/rtems/6" 6/rtems-arm
4. Build and install the RTEMS Board Support Packages (BSP) you want to use:
.. code-block:: none
$ cd "$sandbox"
$ cd rtems
$ echo -e "[arm/xilinx_zynq_a9_qemu]\nRTEMS_POSIX_API = True" > config.ini
$ ./waf configure --prefix "$sandbox/rtems/6"
$ ./waf
$ ./waf install
5. Populate the ``rtems_waf`` git submodule. Note, make sure you specify
``rtems_waf`` or the FreeBSD kernel source will be cloned:
.. code-block:: none
$ cd "$sandbox"
$ cd rtems-libbsd
$ git submodule init
$ git submodule update rtems_waf
6. Run Waf's configure with your specific settings. In this case the path to
the tools and RTEMS are provided on the command line and so do not need to
be in your path or environment, see comment below. You can use
``--rtems-archs=arm,sparc,i386`` or
``--rtems-bsps=arm/xilinx_zynq_a9_qemu,sparc/sis,i386/pc586`` to build for
more than BSP at a time. Note, you must provide the architecture and BSP as
a pair. Providing just the BSP name will fail. This call also explicitly
provides a buildset via the ``--buildset=buildset/default.ini`` option. If no
buildset is provided the default one (which is the same as the one provided
explicitly here) will be used. You can also provide multiple buildsets as a
coma separated list or via multiple ``--buildset=x`` options.
.. code-block:: none
$ cd "$sandbox"
$ cd rtems-libbsd
$ ./waf configure --prefix="$sandbox/rtems/6" \
--rtems-bsps=arm/xilinx_zynq_a9_qemu \
--buildset=buildset/default.ini
7. Build and install. The LibBSD package will be installed into the prefix
provided to configure:
.. code-block:: none
$ cd "$sandbox"
$ cd rtems-libbsd
$ ./waf
$ ./waf install
9. Run the tests:
.. code-block:: none
$ cd "$sandbox"
$ cd rtems-libbsd
$ ../rtems/6/bin/rtems-test --rtems-bsp=xilinx_zynq_a9_qemu build
It is good practice to keep your environment as empty as possible. Setting
paths to tools or specific values to configure or control a build is dangerous
because settings can leak between different builds and change what you expect a
build to do. The Waf tool used here lets you specify on the command line the
tools and RTEMS paths and this is embedded in Waf's configuration information.
If you have a few source trees working at any one time with different tool sets
or configurations you can easly move between them safe in the knowledge that
one build will not infect another.
Branches
========
master
This branch is intended for the RTEMS master which tracks the FreeBSD
master branch. This branch must be used for libbsd development. Back
ports to the 6-freebsd-12 are allowed.
6-freebsd-12
This branch is intended for RTEMS 6 which tracks the FreeBSD stable/12
branch. This branch is maintained and regular updates from FreeBSD are
planned. It is recommended for production systems.
5-freebsd-12
This branch belongs to the RTEMS 5 release. It is based on FreeBSD
stable/12 branch. It is recommended for production systems that use
RTEMS 5.
5
This branch belongs to the RTEMS 5 release. It is based on a FreeBSD
development version. This branch is unmaintained. Use 5-freebsd-12 for
RTEMS 5.
freebsd-9.3
Is the branch for some RTEMS version with a FreeBSD 9.3 baseline. This
branch is unmaintained. It is recommended to update to RTEMS 5 or 6.
4.11
Is the branch for the RTEMS 4.11 release series. This branch is
unmaintained. It is recommended to update to RTEMS 5 or 6.
Updating RTEMS Waf Support
==========================
If you have a working libbsd repository and new changes to the ``rtems_waf``
submodule has been made, you will need update. A ``git status`` will indicate
there are new commits with:
.. code-block:: none
$ git status
[ snip output ]
modified: rtems_waf (new commits)
[ snip output ]
To update:
.. code-block:: none
$ git submodule update rtems_waf
Please make sure you use the exact command or you might find you are cloning
the whole of the FreeBSD source tree. If that happens simply git ^C and try
again.
FreeBSD Kernel Options
======================
You can set FreeBSD kernel options during build configuration with the
--freebsd-option=a,b,c,... configuration command option. This is an advanced
option and should only be used if you are familiar with the internals of the
FreeBSD kernel and what these options do. Each of the comma separated options
is converted to uppercase and passed as a compiler command line define (-D).
The options are listed in the FreeBSD
`NOTES <https://github.com/freebsd/freebsd/blob/master/sys/conf/NOTES>`_
file.
An example to turn on a verbose kernel boot, verbose sysinit and bus debugging
configure with:
.. code-block:: none
--freebsd-options=bootverbose,verbose_sysinit,bus_debug
To enable kernel internal consistency checking use:
.. code-block:: none
--freebsd-options=invariants,invariant_support
SMP Requirements
================
In order to support
`EPOCH(9) <https://www.freebsd.org/cgi/man.cgi?query=epoch&apropos=0&sektion=9>`_
a scheduler with thread pinning support is required. This is the case if you
use the default scheduler configuration. EPOCH(9) is a central synchronization
mechanism of the network stack.
Qemu and Networking
===================
You can use the Qemu simulator to run a LibBSD based application and connect it
to a virtual network on your host. You have to create a TAP virtual Ethernet
interface for this:
.. code-block:: none
sudo tunctl -p -t qtap -u $(whoami)
sudo ip link set dev qtap up
sudo ip addr add 169.254.1.1/16 dev qtap
You can show the interface state with the following command:
.. code-block:: none
$ ip addr show qtap
27: qtap: <NO-CARRIER,BROADCAST,MULTICAST,UP> mtu 1500 qdisc pfifo_fast state DOWN group default qlen 1000
link/ether 8e:50:a2:fb:e1:3b brd ff:ff:ff:ff:ff:ff
inet 169.254.1.1/16 scope global qtap
valid_lft forever preferred_lft forever
You may have to assign the interface to a firewall zone.
The Qemu command line varies by board support package, here is an example for
the arm/xilinx_zynq_a9_qemu BSP:
.. code-block:: none
qemu-system-arm -serial null -serial mon:stdio -nographic \
-M xilinx-zynq-a9 -m 256M \
-net tap,ifname=qtap,script=no,downscript=no \
-net nic,model=cadence_gem,macaddr=0e:b0:ba:5e:ba:12 \
-kernel build/arm-rtems6-xilinx_zynq_a9_qemu-default/media01.exe
After some seconds it will acquire a IPv4 link-local address, e.g.
.. code-block:: none
info: cgem0: probing for an IPv4LL address
debug: cgem0: checking for 169.254.159.156
You can connect to the target via telnet for example:
.. code-block:: none
$ telnet 169.254.159.156
Trying 169.254.159.156...
Connected to 169.254.159.156.
Escape character is '^]'.
RTEMS Shell on /dev/pty4. Use 'help' to list commands.
TLNT [/] #