source: rtems-libbsd/libbsd.txt @ ec94238

4.1155-freebsd-126-freebsd-12freebsd-9.3
Last change on this file since ec94238 was 9e3ba38, checked in by Joel Sherrill <joel.sherrill@…>, on 03/09/12 at 19:09:29

Add URL to FreeBSD SVN tarball.

  • Property mode set to 100644
File size: 7.5 KB
Line 
1RTEMS BSD USB and TCP/IP Developers Guide
2=========================================
3Joel Sherrill <joel.sherrill@oarcorp.com>
4:Author Initials: JRS
5:toc:
6:icons:
7:numbered:
8:website: http://www.rtems.org/
9
10RTEMS uses FreeBSD as the source of its TCP/IP and USB stacks.
11This is a developers guide which captures information on the
12process of merging code from FreeBSD, building this library,
13RTEMS specific support files, and general guidelines on what
14modifications to the FreeBSD source are permitted.
15
16Goals of this effort are:
17
18* Update TCP/IP and provide USB in RTEMS
19* Ease updating to future FreeBSD versions
20* Ease tracking changes in FreeBSD code
21* Minimize manual changes in FreeBSD code
22* Define stable kernel/device driver API which is implemented
23by both RTEMS and FreeBSD. This is the foundation of the port.
24
25We will work to push our changes upstream to the FreeBSD Project
26and minimize changes required at each update point.
27
28**************************************************************
29This is a work in progress and is very likely to be incomplete.
30Please help by adding to it.
31**************************************************************
32
33== Source Code Version Information
34
35* FreeBSD 8.2 SVN r222496
36* RTEMS 4.11
37  - BSP must have support for all new BSD sys sections
38  - It is preferable if the BSP uses linkcmds.base.
39  - BSP must be from an architecture with Programmable Interrupt Controller
40    interrupt model.
41
42The FreeBSD 8.2 SVN checkout will generally be referred to as the
43FreeBSD source in this document. An archive of the FreeBSD 8.2 SVN
44archive used is located at http://www.rtems.org/ftp/pub/rtems/people/joel/freebsd
45
46== To Do
47* Adapt generic IRQ PIC interface code to Simple Vectored Interrupt Model
48  so that those architectures can use new TCP/IP and USB code.
49* in_cksum implementations for architectures not supported by FreeBSD.
50  This will require figuring out where to put implementations that do
51  not originate from FreeBSD and are populated via the script.
52* generic in_cksum implementation is missing in_cksum_split so currently
53  cannot be used.
54
55== FreeBSD Source
56
57You should be able to rely on FreebSD manual pages and documentation
58for details on the code itself.
59
60=== Automatically Generated FreeBSD Files
61
62The FreeBSD source tarball includes a file named Makefile.rtems which
63has stanzas to automatically generate some files using awk. For details
64on this, see http://www.freebsd.org/cgi/man.cgi?query=kobj&apropos=0&sektion=0&manpath=FreeBSD+9.0-RELEASE&arch=default&format=html
65
66XXX This needs more detail.
67
68=== Rules for Modifying FreeBSD Source
69
70* Only add lines.  Subtract code by added "ifndef __rtems__". This makes
71merging easier in the future.
72
73== libbsd Source
74
75=== What is in git
76
77The git source is a self-contained kit with FreeBSD and RTEMS components
78pre-merged. The Makefile in this kit is automatically generated.
79
80Any changes to sources in the freebsd or contrib directories will need to
81be merged upstream into our master FreeBSD svn checkout.
82
83=== Building RTEMS libbsd source
84
85You need to configure RTEMS for the desired BSP and install it. The
86following is the script used to build the powerpc/psim BSP for our
87internal testing purposes:
88
89[listing]
90----
91#! /bin/sh
92
93cd ${HOME}/newbsd
94rm -rf b-psim
95mkdir b-psim
96cd b-psim
97../git/rtems/configure --target=powerpc-rtems4.11 \
98  --enable-rtemsbsp=psim --disable-networking \
99  --enable-tests=samples \
100  --prefix=${HOME}/newbsd/bsp-install >c.log 2>&1 && \
101  make >b.log 2>&1 && \
102  make install >i.log 2>&1
103echo $?
104----
105
106Then edit the file config.inc to set RTEMS_MAKEFILE_PATH appropriately
107to indicate the ${prefix}/${target}/${BSP}.  Continuing on the above,
108the config.inc used to match the above is:
109
110[listing]
111----
112RTEMS_MAKEFILE_PATH = ${HOME}/newbsd/bsp-install/powerpc-rtems4.11/psim/
113INSTALL_BASE = ${HOME}/newbsd/install
114----
115
116The above installs the RTEMS libbsd kit into a separate place from
117RTEMS and the BSP. The RTEMS libbsd tests are built against an installed
118image of the RTEMS libbsd. By keeping it in a separate installation point
119from RTEMS itself, this makes it easier to remove a libbsd installation
120and have a clean test point.
121
122[listing]
123----
124make
125make install
126make -C testsuite
127----
128
129At this point, we expect multiple linker errors. That is what we are
130currently working on.
131
132=== Organization
133
134The top level directory contains a few directories and files. The following
135are important to understand:
136
137* freebsd-to-rtems.py - script to convert to and free FreeBSD and RTEMS trees
138* Makefile - automatically generated
139* contrib/ - from FreeBSD by script.
140* freebsd/ - from FreeBSD by script.
141* rtemsbsd/ - RTEMS specific implementations of FreeBSD kernel support routines.
142* testsuite/ - RTEMS specific tests
143* libbsd.txt - Documentation in Asciidoc
144
145== Moving Code Between FreeBSD SVN and RTEMS libbsd
146
147The script freebsd-to-rtems.py is used to copy code from FreeBSD to the
148RTEMS libbsd tree and to reverse this process. This script attempts to
149automate this process as much as possible and performs some transformations
150on the FreeBSD code. Its command line arguments are shown below:
151
152[listing]
153----
154freebsd-to-rtems.py [args]
155  -?|-h|--help     print this and exit
156  -d|--dry-run     run program but no modifications
157  -e|--early-exit  evaluate arguments, print results, and exit
158  -m|--makefile    just generate Makefile
159  -R|--reverse     default FreeBSD -> RTEMS, reverse that
160  -r|--rtems       RTEMS directory
161  -f|--freebsd     FreeBSD directory
162  -v|--verbose     enable verbose output mode
163----
164
165In its default mode of operation, freebsd-to-rtems.py is used to copy code
166from FreeBSD to the RTEMS libbsd tree and perform transformations.  In forward
167mode, the script may be requested to just generate the Makefile.
168
169In "reverse mode", this script undoes those transformations and copies
170the source code back to the FreeBSD SVN tree. This allows us to do
171'svn diff', evaluate changes made by the RTEMS Project, and report changes
172back to FreeBSD upstream.
173
174In either mode, the script may be asked to perform a dry-run or be verbose.
175Also, in either mode, the script is also smart enough to avoid copying over
176files which have not changed. This means that the timestamps of files are
177not changed unless the contents change. The script will also report the
178number of files which changed. In verbose mode, the script will print
179the name of the files which are changed.
180
181The following is an example forward run with no changes.
182
183[listing]
184----
185$ ~/newbsd/git/libbsd-8.2/freebsd-to-rtems.py \
186    -r /home/joel/newbsd/git/libbsd-8.2 \
187    -f /home/joel/newbsd/libbsd/freebsd-8.2 -v
188Verbose:                yes
189Dry Run:                no
190Only Generate Makefile: no
191RTEMS Directory:        /home/joel/newbsd/git/libbsd-8.2
192FreeBSD Directory:      /home/joel/newbsd/libbsd/freebsd-8.2
193Direction:              forward
194Generating into /home/joel/newbsd/git/libbsd-8.2
1950 files were changed.
196----
197
198== Initialization of RTEMS Libbsd
199
200The initialization of the RTEMS Libbsd is based on the FreeBSD SYSINIT
201infrastructure. This is simply because we are initializing a subset of
202FreeBSD. For details refer to http://www.freebsd.org/cgi/man.cgi?query=SYSINIT&sektion=9&apropos=0&manpath=FreeBSD+9-current
203
204The key to initializing a system is to ensure that the desired device
205drivers are explicitly pulled into the linked application. This plus
206linking against the Libsd library will pull in the necessary FreeBSD
207infrastructure. The SYSINIT structures are automatically built at link
208time and the various initialization routines will thus be executed in'
209the correct order.
210
211XXX This needs more details.
Note: See TracBrowser for help on using the repository browser.