Changeset e3e88e1 in rtems-libbsd
- Timestamp:
- 06/26/17 07:36:56 (7 years ago)
- Branches:
- 5, 5-freebsd-12, 6-freebsd-12, master
- Children:
- 127296c
- Parents:
- 9db59c7
- Files:
-
- 1 added
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
libbsd.txt
r9db59c7 re3e88e1 563 563 for details on the code itself. 564 564 565 === Automatically Generated FreeBSD Files566 567 Some source and header files are automatically generated during the FreeBSD568 build process. The `Makefile.todo` file performs this manually. The should be569 included in `freebsd-to-rtems.py` script some time in the future. For details,570 see also571 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 Source574 575 Only add lines. If your patch contains lines starting with a '-', then this is576 wrong. Subtract code by added `#ifndef __rtems__`. This makes merging easier577 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_mtx604 * none not locked605 */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_boot615 #endif /* __rtems__ */616 617 #endif /* _KERNEL */618 -------------------------------------------------------------------------------619 620 Add nothing (even blank lines) before or after the `__rtems__` guards. Always621 include a `__rtems__` in the guards to make searches easy, so use622 623 * `#ifndef __rtems__`,624 * `#ifdef __rtems__`,625 * `#else /* __rtems__ */`, and626 * `#endif /* __rtems__ */`.627 628 The guards must start at the begin of the line. Examples for wrong guards:629 630 -------------------------------------------------------------------------------631 static void632 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 void643 missing_rtems_comments_in_the_guards(int j)644 {645 646 #ifdef __rtems__647 return (j + 3);648 #else649 return (j + 4);650 #endif651 }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 is656 transformed by the import script into `#include <rtems/bsd/local/opt_xyz.h>`. Do657 not disable option header includes via guards. Instead, add an empty option658 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 use669 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 673 565 == BSD Library Source 674 675 === What is in the Git Repository676 677 There is a self-contained kit with FreeBSD and RTEMS components pre-merged. The678 Waf wscript in this kit is automatically generated.679 680 Any changes to source in the `freebsd` directories will need to be merged681 upstream into our master FreeBSD checkout, the `freebsd-org` submodule.682 683 The repository contains two FreeBSD source trees. In the `freebsd` directory684 are the so called 'managed' FreeBSD sources used to build the BSD library. The685 FreeBSD source in `freebsd-org` is the 'master' version. The686 `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 need688 to run the script in 'revert' or 'reverse' mode using the `-R` switch. This689 will copy the source back to your local copy of the master FreeBSD source so690 you can run `git diff` against the upstream FreeBSD source. If you want to691 transfer source files from the master FreeBSD source to the manged FreeBSD692 sources, then you must run the script in 'forward' mode (the default).693 694 === Organization695 696 The top level directory contains a few directories and files. The following697 are important to understand698 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, and705 * `libbsd.txt` - documentation in Asciidoc.706 707 == Moving Code Between Managed and Master FreeBSD Source708 709 The script `freebsd-to-rtems.py` is used to copy code from FreeBSD to the710 rtems-libbsd tree and to reverse this process. This script attempts to711 automate this process as much as possible and performs some transformations712 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 exit717 -d|--dry-run run program but no modifications718 -D|--diff provide diff of files between trees719 -e|--early-exit evaluate arguments, print results, and exit720 -m|--makefile Warning: depreciated and will be removed721 -b|--buildscripts just generate the build scripts722 -S|--stats Print a statistics report723 -R|--reverse default FreeBSD -> RTEMS, reverse that724 -r|--rtems RTEMS Libbsd directory (default: '.')725 -f|--freebsd FreeBSD SVN directory (default: 'freebsd-org')726 -v|--verbose enable verbose output mode727 ----728 729 In its default mode of operation, freebsd-to-rtems.py is used to copy code730 from FreeBSD to the rtems-libbsd tree and perform transformations. In forward731 mode, the script may be requested to just generate the Waf script.732 733 In "reverse mode", this script undoes those transformations and copies734 the source code back to the FreeBSD SVN tree. This allows us to do735 'svn diff', evaluate changes made by the RTEMS Project, and report changes736 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 over740 files which have not changed. This means that the timestamps of files are741 not changed unless the contents change. The script will also report the742 number of files which changed. In verbose mode, the script will print743 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 file747 is not present at the destination for the direction. This can happen as files748 not avaliable at the FreeBSD snapshot point have been specially added to the749 RTEMS FreeBSD tree. Warnings can also appear if you have changed the list of750 files in libbsd.py. The reverse mode will result in the FreeBSD having751 uncommitted changes. You can ignore these. Once the reverse process has752 finished edit libbsd.py and add any new files then run the forwad mode to bring753 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 -v761 Verbose: yes (1)762 Dry Run: no763 Only Generate Makefile: no764 RTEMS Directory: /home/joel/newbsd/git/libbsd-8.2765 FreeBSD Directory: /home/joel/newbsd/libbsd/freebsd-8.2766 Direction: forward767 Generating into /home/joel/newbsd/git/libbsd-8.2768 0 files were changed.769 ----770 771 The script may also be used to generate a diff in either forward or reverse772 direction.773 774 You can add more than one verbose option (-v) to the command line and get more775 detail and debug level information from the command.776 777 == FreeBSD version of imported files and directories778 779 . *, trunk, 2017-04-04, 642b174daddbd0efd9bb5f242c43f4ab4db6869f.780 781 == How to import code from FreeBSD782 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 to797 FreeBSD. If the code has been reserved into the original FreeBSD tree it will798 show nothing has changed. To see what we have change:799 800 $ cd freebsd-org801 $ git checkout -- .802 $ cd ..803 $ ./freebsd-to-rtems.py -R -S -d804 805 The report lists the files change based on the opacity level. The opacity is a806 measure on how much of a file differs from the original FreeBSD source. The807 lower the value the more transparent the source file it.808 809 == Porting of userspace utilities810 811 The theory behind the described method is to put all BSS and initialized data812 objects into a named section. This section then will be saved before the code is813 executed and restored after it has finished. This method limits to a single814 threaded execution of the application but minimizes the necessary changes to the815 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 patches820 should go back to the upstream FreeBSD sources.821 . Move static variables out of functions if necessary (search for822 "<TAB>static"). These patches most likely will not be accepted into FreeBSD.823 . Add a rtems_bsd_command_PROGNAME() wrapper function to the source file824 containing the main function (e.g. PROGNAME = pfctl). For an example look at825 `rtems_bsd_command_pfctl()` in `freebsd/sbin/pfctl/pfctl.c`.826 . You probably have to use getopt_r() instead of getopt(). Have a look at827 `freebsd/sbin/pfctl/pfctl.c`.828 . Build the libbsd without optimization.829 . Use the `userspace-header-gen.py` to generate some necessary header830 files. It will generate one `rtems-bsd-PROGNAME-MODULE-data.h` per object file, one831 `rtems-bsd-PROGNAME-namespace.h` and one `rtems-bsd-PROGNAME-data.h`. To call832 the script, you have to compile the objects and afterwards run the helper833 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. It836 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 to838 remove RTEMS-specific names from the namespace. The defaults (linker set names839 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 and842 the `PROGNAME-rtems-bsd-MODULE-data.h` after the include section of the843 corresponding source files.844 . Include `machine/rtems-bsd-program.h` at the top of the include block in each845 source file.846 . Create one compilable commit.847 566 848 567 == Initialization of the BSD Library
Note: See TracChangeset
for help on using the changeset viewer.