Changeset e3e88e1 in rtems-libbsd


Ignore:
Timestamp:
06/26/17 07:36:56 (7 years ago)
Author:
Sebastian Huber <sebastian.huber@…>
Branches:
5, 5-freebsd-12, 6-freebsd-12, master
Children:
127296c
Parents:
9db59c7
Message:

Add CONTRIBUTING.md

Files:
1 added
1 edited

Legend:

Unmodified
Added
Removed
  • libbsd.txt

    r9db59c7 re3e88e1  
    563563for details on the code itself.
    564564
    565 === Automatically Generated FreeBSD Files
    566 
    567 Some source and header files are automatically generated during the FreeBSD
    568 build process.  The `Makefile.todo` file performs this manually.  The should be
    569 included in `freebsd-to-rtems.py` script some time in the future.  For details,
    570 see also
    571 http://www.freebsd.org/cgi/man.cgi?query=kobj&sektion=9&apropos=0&manpath=FreeBSD+9.2-RELEASE[KOBJ(9)].
    572 
    573 === Rules for Modifying FreeBSD Source
    574 
    575 Only add lines.  If your patch contains lines starting with a '-', then this is
    576 wrong.  Subtract code by added `#ifndef __rtems__`.  This makes merging easier
    577 in the future.  For example:
    578 
    579 -------------------------------------------------------------------------------
    580 /* Global variables for the kernel. */
    581 
    582 #ifndef __rtems__
    583 /* 1.1 */
    584 extern char kernelname[MAXPATHLEN];
    585 #endif /* __rtems__ */
    586 
    587 extern int tick;                        /* usec per tick (1000000 / hz) */
    588 -------------------------------------------------------------------------------
    589 
    590 -------------------------------------------------------------------------------
    591 #if defined(_KERNEL) || defined(_WANT_FILE)
    592 #ifdef __rtems__
    593 #include <rtems/libio_.h>
    594 #include <sys/fcntl.h>
    595 #endif /* __rtems__ */
    596 /*
    597  * Kernel descriptor table.
    598  * One entry for each open kernel vnode and socket.
    599  *
    600  * Below is the list of locks that protects members in struct file.
    601  *
    602  * (f) protected with mtx_lock(mtx_pool_find(fp))
    603  * (d) cdevpriv_mtx
    604  * none not locked
    605  */
    606 -------------------------------------------------------------------------------
    607 
    608 -------------------------------------------------------------------------------
    609 extern int profprocs;                   /* number of process's profiling */
    610 #ifndef __rtems__
    611 extern volatile int ticks;
    612 #else /* __rtems__ */
    613 #include <rtems/score/watchdogimpl.h>
    614 #define ticks _Watchdog_Ticks_since_boot
    615 #endif /* __rtems__ */
    616 
    617 #endif /* _KERNEL */
    618 -------------------------------------------------------------------------------
    619 
    620 Add nothing (even blank lines) before or after the `__rtems__` guards.  Always
    621 include a `__rtems__` in the guards to make searches easy, so use
    622 
    623 * `#ifndef __rtems__`,
    624 * `#ifdef __rtems__`,
    625 * `#else /* __rtems__ */`, and
    626 * `#endif /* __rtems__ */`.
    627 
    628 The guards must start at the begin of the line.  Examples for wrong guards:
    629 
    630 -------------------------------------------------------------------------------
    631 static void
    632 guards_must_start_at_the_begin_of_the_line(int j)
    633 {
    634 
    635         #ifdef __rtems__
    636         return (j + 1);
    637         #else /* __rtems__ */
    638         return (j + 2);
    639         #endif /* __rtems__ */
    640 }
    641 
    642 static void
    643 missing_rtems_comments_in_the_guards(int j)
    644 {
    645 
    646 #ifdef __rtems__
    647         return (j + 3);
    648 #else
    649         return (j + 4);
    650 #endif
    651 }
    652 -------------------------------------------------------------------------------
    653 
    654 The FreeBSD build and configuration system uses option header files, e.g.
    655 `#include "opt_xyz.h"` in an unmodified FreeBSD file.  This include is
    656 transformed by the import script into `#include <rtems/bsd/local/opt_xyz.h>`.  Do
    657 not disable option header includes via guards.  Instead, add an empty option
    658 header, e.g. `touch rtemsbsd/include/rtems/bsd/local/opt_xyz.h`.
    659 -------------------------------------------------------------------------------
    660 /* WRONG */
    661 #ifndef __rtems__
    662 #include <rtems/bsd/local/opt_xyz.h>
    663 #endif /* __rtems__ */
    664 -------------------------------------------------------------------------------
    665 
    666 In general, provide empty header files and do not guard includes.
    667 
    668 For new code use
    669 http://www.freebsd.org/cgi/man.cgi?query=style&apropos=0&sektion=9&manpath=FreeBSD+9.2-RELEASE&arch=default&format=html[STYLE(9)].
    670 
    671 Do not format original FreeBSD code.
    672 
    673565== BSD Library Source
    674 
    675 === What is in the Git Repository
    676 
    677 There is a self-contained kit with FreeBSD and RTEMS components pre-merged. The
    678 Waf wscript in this kit is automatically generated.
    679 
    680 Any changes to source in the `freebsd` directories will need to be merged
    681 upstream into our master FreeBSD checkout, the `freebsd-org` submodule.
    682 
    683 The repository contains two FreeBSD source trees.  In the `freebsd` directory
    684 are the so called 'managed' FreeBSD sources used to build the BSD library.  The
    685 FreeBSD source in `freebsd-org` is the 'master' version.  The
    686 `freebsd-to-rtems.py` script is used to transfer files between the two trees.
    687 In general terms, if you have modified managed FreeBSD sources, you will need
    688 to run the script in 'revert' or 'reverse' mode using the `-R` switch.  This
    689 will copy the source back to your local copy of the master FreeBSD source so
    690 you can run `git diff` against the upstream FreeBSD source.  If you want to
    691 transfer source files from the master FreeBSD source to the manged FreeBSD
    692 sources, then you must run the script in 'forward' mode (the default).
    693 
    694 === Organization
    695 
    696 The top level directory contains a few directories and files. The following
    697 are important to understand
    698 
    699 * `freebsd-to-rtems.py` - script to convert to and free FreeBSD and RTEMS trees,
    700 * `create-kernel-namespace.sh` - script to create the kernel namespace header <machine/rtems-bsd-kernel-namespace.h,
    701 * `wscript` - automatically generated,
    702 * `freebsd/` - from FreeBSD by script,
    703 * `rtemsbsd/` - RTEMS specific implementations of FreeBSD kernel support routines,
    704 * `testsuite/` - RTEMS specific tests, and
    705 * `libbsd.txt` - documentation in Asciidoc.
    706 
    707 == Moving Code Between Managed and Master FreeBSD Source
    708 
    709 The script `freebsd-to-rtems.py` is used to copy code from FreeBSD to the
    710 rtems-libbsd tree and to reverse this process. This script attempts to
    711 automate this process as much as possible and performs some transformations
    712 on the FreeBSD code. Its command line arguments are shown below:
    713 
    714 ----
    715 freebsd-to-rtems.py [args]
    716   -?|-h|--help      print this and exit
    717   -d|--dry-run      run program but no modifications
    718   -D|--diff         provide diff of files between trees
    719   -e|--early-exit   evaluate arguments, print results, and exit
    720   -m|--makefile     Warning: depreciated and will be removed
    721   -b|--buildscripts just generate the build scripts
    722   -S|--stats        Print a statistics report
    723   -R|--reverse      default FreeBSD -> RTEMS, reverse that
    724   -r|--rtems        RTEMS Libbsd directory (default: '.')
    725   -f|--freebsd      FreeBSD SVN directory (default: 'freebsd-org')
    726   -v|--verbose      enable verbose output mode
    727 ----
    728 
    729 In its default mode of operation, freebsd-to-rtems.py is used to copy code
    730 from FreeBSD to the rtems-libbsd tree and perform transformations.  In forward
    731 mode, the script may be requested to just generate the Waf script.
    732 
    733 In "reverse mode", this script undoes those transformations and copies
    734 the source code back to the FreeBSD SVN tree. This allows us to do
    735 'svn diff', evaluate changes made by the RTEMS Project, and report changes
    736 back to FreeBSD upstream.
    737 
    738 In either mode, the script may be asked to perform a dry-run or be verbose.
    739 Also, in either mode, the script is also smart enough to avoid copying over
    740 files which have not changed. This means that the timestamps of files are
    741 not changed unless the contents change. The script will also report the
    742 number of files which changed. In verbose mode, the script will print
    743 the name of the files which are changed.
    744 
    745 To add or update files in the RTEMS FreeBSD tree first run the 'reverse mode'
    746 and move the current set of patches FreeBSD. The script may warn you if a file
    747 is not present at the destination for the direction. This can happen as files
    748 not avaliable at the FreeBSD snapshot point have been specially added to the
    749 RTEMS FreeBSD tree. Warnings can also appear if you have changed the list of
    750 files in libbsd.py. The reverse mode will result in the FreeBSD having
    751 uncommitted changes. You can ignore these. Once the reverse process has
    752 finished edit libbsd.py and add any new files then run the forwad mode to bring
    753 those files into the RTEMS FreeBSD tree.
    754 
    755 The following is an example forward run with no changes.
    756 
    757 ----
    758 $ ~/newbsd/git/libbsd-8.2/freebsd-to-rtems.py \
    759     -r /home/joel/newbsd/git/libbsd-8.2 \
    760     -f /home/joel/newbsd/libbsd/freebsd-8.2 -v
    761 Verbose:                yes (1)
    762 Dry Run:                no
    763 Only Generate Makefile: no
    764 RTEMS Directory:        /home/joel/newbsd/git/libbsd-8.2
    765 FreeBSD Directory:      /home/joel/newbsd/libbsd/freebsd-8.2
    766 Direction:              forward
    767 Generating into /home/joel/newbsd/git/libbsd-8.2
    768 0 files were changed.
    769 ----
    770 
    771 The script may also be used to generate a diff in either forward or reverse
    772 direction.
    773 
    774 You can add more than one verbose option (-v) to the command line and get more
    775 detail and debug level information from the command.
    776 
    777 == FreeBSD version of imported files and directories
    778 
    779 . *, trunk, 2017-04-04, 642b174daddbd0efd9bb5f242c43f4ab4db6869f.
    780 
    781 == How to import code from FreeBSD
    782 
    783 . In case you import files from a special FreeBSD version, then update the list above.
    784 . Run `git status` and make sure your working directory is clean.
    785 . Run `./freebsd-to-rtems.py -R`
    786 . Run `./freebsd-to-rtems.py`
    787 . 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.
    788 . Add the files to import to `libbsd.py`.
    789 . Run `./freebsd-to-rtems.py`
    790 . Immediately check in the imported files without the changes to `libbsd_waf.py`.  Do not touch the imported files yourself at this point.
    791 . Port the imported files to RTEMS.  See 'Rules for Modifying FreeBSD Source'.
    792 . Add a test to the testsuite if possible.
    793 . 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`.
    794 . Create one commit from this.
    795 
    796 The -S or --stats option generates reports the changes we have made to
    797 FreeBSD. If the code has been reserved into the original FreeBSD tree it will
    798 show nothing has changed. To see what we have change:
    799 
    800  $ cd freebsd-org
    801  $ git checkout -- .
    802  $ cd ..
    803  $ ./freebsd-to-rtems.py -R -S -d
    804 
    805 The report lists the files change based on the opacity level. The opacity is a
    806 measure on how much of a file differs from the original FreeBSD source. The
    807 lower the value the more transparent the source file it.
    808 
    809 == Porting of userspace utilities
    810 
    811 The theory behind the described method is to put all BSS and initialized data
    812 objects into a named section. This section then will be saved before the code is
    813 executed and restored after it has finished. This method limits to a single
    814 threaded execution of the application but minimizes the necessary changes to the
    815 original FreeBSD code.
    816 
    817 . Import and commit the unchanged source files like described above.
    818 . Add the files to the libbsd.py and build them.
    819 . Check the sources for everything that can be made const. This type of patches
    820   should go back to the upstream FreeBSD sources.
    821 . Move static variables out of functions if necessary (search for
    822   "<TAB>static"). These patches most likely will not be accepted into FreeBSD.
    823 . Add a rtems_bsd_command_PROGNAME() wrapper function to the source file
    824   containing the main function (e.g. PROGNAME = pfctl). For an example look at
    825   `rtems_bsd_command_pfctl()` in `freebsd/sbin/pfctl/pfctl.c`.
    826 . You probably have to use getopt_r() instead of getopt(). Have a look at
    827   `freebsd/sbin/pfctl/pfctl.c`.
    828 . Build the libbsd without optimization.
    829 . Use the `userspace-header-gen.py` to generate some necessary header
    830   files. It will generate one `rtems-bsd-PROGNAME-MODULE-data.h` per object file, one
    831   `rtems-bsd-PROGNAME-namespace.h` and one `rtems-bsd-PROGNAME-data.h`. To call
    832   the script, you have to compile the objects and afterwards run the helper
    833   script with a call similar to this one:
    834   `python ./userspace-header-gen.py build/arm-rtems4.12-xilinx_zynq_a9_qemu/freebsd/sbin/pfctl/*.o -p pfctl`
    835   Replace the name (given via -p option) by the name of the userspace tool. It
    836   has to match the name that is used in the RTEMS linker set further below.
    837 . If you regenerated files that have already been generated, you may have to
    838   remove RTEMS-specific names from the namespace. The defaults (linker set names
    839   and rtems_bsd_program_xxx) should already be filtered.
    840 . Put the generated header files into the same folder like the source files.
    841 . Include `PROGNAME-rtems-bsd-namespace.h` at the top of each source file and
    842   the `PROGNAME-rtems-bsd-MODULE-data.h` after the include section of the
    843   corresponding source files.
    844 . Include `machine/rtems-bsd-program.h` at the top of the include block in each
    845   source file.
    846 . Create one compilable commit.
    847566
    848567== Initialization of the BSD Library
Note: See TracChangeset for help on using the changeset viewer.