From 63228df30d5b5d6ccf5e3c4108fba18041aad692 Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Thu, 19 May 2022 12:58:20 +0200 Subject: Convert *.md files to reST The reST format is used by the standard RTEMS documentation. --- CONTRIBUTING.md | 403 ------------------------------------------------- CONTRIBUTING.rst | 451 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 307 ------------------------------------- README.rst | 329 ++++++++++++++++++++++++++++++++++++++++ 4 files changed, 780 insertions(+), 710 deletions(-) delete mode 100644 CONTRIBUTING.md create mode 100644 CONTRIBUTING.rst delete mode 100644 README.md create mode 100644 README.rst diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index cb2bbeb1..00000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,403 +0,0 @@ -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 -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 is automatically generated. - -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 -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. -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 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). - -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 RTEMS, reverse that - -r|--rtems RTEMS Libbsd directory (default: '.') - -f|--freebsd FreeBSD SVN directory (default: 'freebsd-org') - -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 -the source code back to the *master* FreeBSD tree. This allows us to do -'git diff', evaluate changes made by the RTEMS Project, and report changes -back to FreeBSD upstream. - -In either mode, the script may be asked to perform a dry-run or be verbose. -Also, in either mode, the script is also smart enough to avoid copying over -files which have not changed. This means that the timestamps of files are -not changed unless the contents change. The script will also report the -number of files which changed. In verbose mode, the script will print -the name of the files which are changed. - -To add or update files in the RTEMS FreeBSD tree first run the *reverse mode* -and move the current set of patches FreeBSD. The script may warn you if a file -is not present at the destination for the direction. This can happen as files -not avaliable at the FreeBSD snapshot point have been specially added to the -RTEMS FreeBSD tree. Warnings can also appear if you have changed the list of -files in libbsd.py. The reverse mode will result in the FreeBSD having -uncommitted changes. You can ignore these. Once the reverse process has -finished edit libbsd.py and add any new files then run the forwad mode to bring -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: -``` - -The script may also be used to generate a diff in either forward or reverse -direction. - -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 -``` -to figure out the current FreeBSD baseline. - -Updates to FreeBSD or RTEMS Kernel Support ------------------------------------------- - -If you update code or change any defines that effect the generated -code in the following paths: - -* `freebsd/sys/*.[ch]` -* `rtemsbsd/rtems/rtems-kernel-*.c` - -you need to see if any new kernel symbols have been generated or -exposed. The tool `rtems-kern-symbols` command supports checking and -updating the kernel symbol namespace. - -The public (global) kernel symbosl need to reside in a private -namespace to avoid clashing with symbols in the user space code or -applications. The FreeBSD kernel names functions and variables -assuming a private kernel only symbols space. RTEMS builds FreeBSD -kernel and user space code in the same symbols space so there can be -clashes. We manage this by maintaining a header file that maps the -global kernel symbols to a private namespace. For example `malloc` is -mapped to `_bsd_malloc`. - -The set of symbols to map is not easy to obtain because symbols may be -the result of complex preprocessing of the source, the code is -specific to a BSP or the code is controlled by a buildset. - -The approach we use is to not remove symbols unless you are certain -the symbols have been removed from the FreeBSD kernel source. This is -a manual operation. - -You are required to check symbols with a 32bit and 64bit -architecture. - -If you are working on a specific BSP and related drivers please make -sure the kernel symbols are checked. It is too much to ask every -developer to build all BSPs and check. - -RTEMS Kernel Symbols Tool -~~~~~~~~~~~~~~~~~~~~~~~~~ - -The python tool `rtems-kern-symbols` can read a kernel header loading -a previously generated version. This maintains the current symbol set -without you needing to build the object files previously scanned. - -The kernel namespace header can be regenerated from the original -header. This checks the kernel header is already sorted. If you think -there is a sorting issue in the existing header please regenerate -without adding new symbols. - -``` -$ ./rtems-kern-symbols --regenerate --output=tmp.h -``` - -This command needs access to your built RTEMS tools. You can set your -environment `PATH` variable or you can specify the top level path as an argument: -``` -$ ./rtems-kern-symbols --rtems-tools=/opt/work/rtems/6 -``` - -Options: - -* You can provide a different kernel header using the `--kern-header` -argument. The default is the LibbSD header. - -* The `--report` option provides a report. - -* The `--diff` option provides a unified diff of any changes. - -* The `--write` option is needed to write any changes - -* The `--output` option lets you control the output kernel header file - change are written too - -The tool manages a number of exlcuded symbols. These are symbols in -the kernel space that are not mapped to the RTEMS kernel namespace. - -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. -* Port the imported files to RTEMS. See 'Rules for Modifying FreeBSD Source'. -* Add a test to the testsuite if possible. -* Run `./rtems-kern-symbols` as discussed above -* 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 - ``` - -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 -executed and restored after it has finished. This method limits to a single -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. -* 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). -* You probably have to use getopt_r() instead of getopt(). Have a look at - [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 - 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` - 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. -* 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 - #include "rtems-bsd-PROGNAME-namespace.h" - #endif /* __rtems__ */ - ``` - The following command may be useful: - ``` - sed -i 's%#include %#include \n\n#ifdef __rtems__\n#include \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__ */ - ``` - 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 - ``` -* Create one compilable commit. - -Rules for Modifying FreeBSD Source ----------------------------------- - -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: - -```c -/* Global variables for the kernel. */ - -#ifndef __rtems__ -/* 1.1 */ -extern char kernelname[MAXPATHLEN]; -#endif /* __rtems__ */ - -extern int tick; /* usec per tick (1000000 / hz) */ -``` - -```c -#if defined(_KERNEL) || defined(_WANT_FILE) -#ifdef __rtems__ -#include -#include -#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 - */ -``` - -```c -extern int profprocs; /* number of process's profiling */ -#ifndef __rtems__ -extern volatile int ticks; -#else /* __rtems__ */ -#include -#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) -{ - - /* WRONG */ - #ifdef __rtems__ - return (j + 1); - #else /* __rtems__ */ - return (j + 2); - #endif /* __rtems__ */ -} - -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 `. 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 -#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). - -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 -perform white space changes automatically, for example adding a newline to the -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, -see also -[KOBJ(9)](http://www.freebsd.org/cgi/man.cgi?query=kobj&sektion=9&apropos=0). diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst new file mode 100644 index 00000000..c10fa339 --- /dev/null +++ b/CONTRIBUTING.rst @@ -0,0 +1,451 @@ +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 +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 +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. + +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 +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 +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 +space. The FreeBSD build system understands the separation and separately +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 +structured ways to manage the separation. + +LibBSD manages the integration of kernel and user code by knowing the context +of the source code. This lets the merge process handle specific changes each +type of file needs. The build system also uses this information to control the +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 +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 ````, +* ``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 +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: + +.. code-block:: none + + 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 +the source code back to the *master* FreeBSD tree. This allows us to do +'git diff', evaluate changes made by the RTEMS Project, and report changes +back to FreeBSD upstream. + +In either mode, the script may be asked to perform a dry-run or be verbose. +Also, in either mode, the script is also smart enough to avoid copying over +files which have not changed. This means that the timestamps of files are +not changed unless the contents change. The script will also report the +number of files which changed. In verbose mode, the script will print +the name of the files which are changed. + +To add or update files in the RTEMS FreeBSD tree first run the *reverse mode* +and move the current set of patches FreeBSD. The script may warn you if a file +is not present at the destination for the direction. This can happen as files +not avaliable at the FreeBSD snapshot point have been specially added to the +RTEMS FreeBSD tree. Warnings can also appear if you have changed the list of +files in libbsd.py. The reverse mode will result in the FreeBSD having +uncommitted changes. You can ignore these. Once the reverse process has +finished edit libbsd.py and add any new files then run the forwad mode to bring +those files into the RTEMS FreeBSD tree. + +The following is an example forward run with no changes. + +.. 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. + +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 + +.. code-block:: none + + $ git log freebsd-org + +to figure out the current FreeBSD baseline. + +Updates to FreeBSD or RTEMS Kernel Support +========================================== + +If you update code or change any defines that effect the generated +code in the following paths: + +* ``freebsd/sys/*.[ch]`` +* ``rtemsbsd/rtems/rtems-kernel-*.c`` + +you need to see if any new kernel symbols have been generated or +exposed. The tool ``rtems-kern-symbols`` command supports checking and +updating the kernel symbol namespace. + +The public (global) kernel symbosl need to reside in a private +namespace to avoid clashing with symbols in the user space code or +applications. The FreeBSD kernel names functions and variables +assuming a private kernel only symbols space. RTEMS builds FreeBSD +kernel and user space code in the same symbols space so there can be +clashes. We manage this by maintaining a header file that maps the +global kernel symbols to a private namespace. For example ``malloc`` is +mapped to ``_bsd_malloc``. + +The set of symbols to map is not easy to obtain because symbols may be +the result of complex preprocessing of the source, the code is +specific to a BSP or the code is controlled by a buildset. + +The approach we use is to not remove symbols unless you are certain +the symbols have been removed from the FreeBSD kernel source. This is +a manual operation. + +You are required to check symbols with a 32bit and 64bit +architecture. + +If you are working on a specific BSP and related drivers please make +sure the kernel symbols are checked. It is too much to ask every +developer to build all BSPs and check. + +RTEMS Kernel Symbols Tool +========================= + +The python tool ``rtems-kern-symbols`` can read a kernel header loading +a previously generated version. This maintains the current symbol set +without you needing to build the object files previously scanned. + +The kernel namespace header can be regenerated from the original +header. This checks the kernel header is already sorted. If you think +there is a sorting issue in the existing header please regenerate +without adding new symbols. + +.. code-block:: none + + ./rtems-kern-symbols --regenerate --output=tmp.h + +This command needs access to your built RTEMS tools. You can set your +environment ``PATH`` variable or you can specify the top level path as an argument: + +.. code-block:: none + + ./rtems-kern-symbols --rtems-tools=/opt/work/rtems/6 + +Options: + +* You can provide a different kernel header using the ``--kern-header`` +argument. The default is the LibbSD header. + +* The ``--report`` option provides a report. + +* The ``--diff`` option provides a unified diff of any changes. + +* The ``--write`` option is needed to write any changes + +* The ``--output`` option lets you control the output kernel header file + change are written too + +The tool manages a number of exlcuded symbols. These are symbols in +the kernel space that are not mapped to the RTEMS kernel namespace. + +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. +* Port the imported files to RTEMS. See 'Rules for Modifying FreeBSD Source'. +* Add a test to the testsuite if possible. +* Run `./rtems-kern-symbols` as discussed above +* 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: + +.. 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 +executed and restored after it has finished. This method limits to a single +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 ``_ 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 `_. +* You probably have to use getopt_r() instead of getopt(). Have a look at + `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 + 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`` + 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 + installed using pip: + ``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: + + .. code-block:: c + + #ifdef __rtems__ + #include + #include "rtems-bsd-PROGNAME-namespace.h" + #endif /* __rtems__ */ + + The following command may be useful: + + .. code-block:: none + + sed -i 's%#include %#include \n\n#ifdef __rtems__\n#include \n#include "rtems-bsd-PROGNAME-namespace.h"\n#endif /* __rtems__ */%' *.c + +* At the bottom of each source file place the follwing: + + .. code-block:: c + + #ifdef __rtems__ + #include "rtems-bsd-PROGNAME-FILE-data.h" + #endif /* __rtems__ */ + + The following command may be useful: + + .. 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. +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: + +.. code-block:: c + + /* Global variables for the kernel. */ + + #ifndef __rtems__ + /* 1.1 */ + extern char kernelname[MAXPATHLEN]; + #endif /* __rtems__ */ + + extern int tick; /* usec per tick (1000000 / hz) */ + +.. code-block:: c + + #if defined(_KERNEL) || defined(_WANT_FILE) + #ifdef __rtems__ + #include + #include + #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 + */ + +.. code-block:: c + + extern int profprocs; /* number of process's profiling */ + #ifndef __rtems__ + extern volatile int ticks; + #else /* __rtems__ */ + #include + #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: + +.. code-block:: c + + static void + guards_must_start_at_the_begin_of_the_line(int j) + { + + /* WRONG */ + #ifdef __rtems__ + return (j + 1); + #else /* __rtems__ */ + return (j + 2); + #endif /* __rtems__ */ + } + + 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 ``. 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``. + +.. code-block:: c + + /* WRONG */ + #ifndef __rtems__ + #include + #endif /* __rtems__ */ + +In general, provide empty header files and do not guard includes. + +For new code use +`STYLE(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 +perform white space changes automatically, for example adding a newline to the +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, +see also +`KOBJ(9) `_. diff --git a/README.md b/README.md deleted file mode 100644 index 4213051e..00000000 --- a/README.md +++ /dev/null @@ -1,307 +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. - -The following is for maintainer only who need to move libbsd to a newer -versions: - -``` -$ git submodule update rtems_waf -$ cd rtems_waf -$ git checkout master -$ git pull -$ cd .. -$ git commit -m "Update rtems_waf" rtems_waf -``` - -FreeBSD Developer Support -------------------------- - -The --freebsd-option provides a tool you can set special kernel options. This -is a developer tool and should only be used if you are familiar with the -internals of the FreeBSD kernel and what these options do. - -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,debug_locks,ktr,ktr_verbose -``` - -The LibBSD Waf support splits the options and converts them to uppercase and -adds them -D options on the compiler command line. - -The list is: - - bootverbose: Verbose boot of the kernel - verbose_sysinit: Verbose printing of all the SYSINIT calls - bus_debug: Bus debugging support - ktr: Kernel trace - ktr_verbose: Verbose kernel trace - debug_locks: FreeBSD locks debugging - invariants: Invariants build of the kernel - invariant_support: Support for Invariants (needed with invariants) - rtems_bsd_descrip_trace: RTEMS BSD descriptor maping trace - rtems_bsd_syscall_trace: RTEMS BSD system call trace - rtems_bsd_vfs_trace RTEMS VFS to libio trace - -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: 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 [/] # -``` diff --git a/README.rst b/README.rst new file mode 100644 index 00000000..3aeb0307 --- /dev/null +++ b/README.rst @@ -0,0 +1,329 @@ +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 `_ +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,debug_locks,ktr,ktr_verbose + +To enable kernel internal consistency checking use: + +.. code-block:: none + + --freebsd-options=invariants,invariant_support + +The LibBSD Waf support splits the options and converts them to uppercase and +adds them -D options on the compiler command line. The supported options are: + +bootverbose + Verbose boot of the kernel + +verbose_sysinit + Verbose printing of all the SYSINIT calls + +bus_debug + Bus debugging support + +ktr + Kernel trace + +ktr_verbose + Verbose kernel trace + +debug_locks + FreeBSD locks debugging + +invariants + Invariants build of the kernel + +invariant_support + Support for Invariants (needed with invariants) + +rtems_bsd_descrip_trace + RTEMS BSD descriptor maping trace + +rtems_bsd_syscall_trace + RTEMS BSD system call trace + +rtems_bsd_vfs_trace + RTEMS VFS to libio trace + +SMP Requirements +================ + +In order to support +`EPOCH(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: 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 [/] # -- cgit v1.2.3