source: rtems-libbsd/libbsd.txt @ 7326d96

4.115-freebsd-12freebsd-9.3
Last change on this file since 7326d96 was 7326d96, checked in by Joel Sherrill <joel.sherrill@…>, on Mar 12, 2012 at 12:58:24 PM

Add diff mode to freebsd-to-rtems.py

  • Property mode set to 100644
File size: 9.6 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== Issues and To Do
47* Sebastian Huber: mentioned some simple test code which would verify
48  that the BSD code/and or USB stack was initialized.  This has been
49  sent to Joel Sherrill and is pending merger.
50
51* Sebastian Huber and Joel Sherrill discussed the need for a a basic USB
52  functionality test that is known to work on qemu pc.
53
54* Adapt generic IRQ PIC interface code to Simple Vectored Interrupt Model
55  so that those architectures can use new TCP/IP and USB code.
56
57* in_cksum implementations for architectures not supported by FreeBSD.
58  This will require figuring out where to put implementations that do
59  not originate from FreeBSD and are populated via the script.
60
61* FreeBSD generic in_cksum implementation is missing in_cksum_split so
62  currently cannot be used.
63
64* How does one initialize the TCP/IP stack?
65
66* linker section issues: I have undefined symbols for
67  _bsd__start_set_sysinit_set and _bsd__stop_set_sysinit_set.
68  Is this the only type of new section magic?  What about the old sysctl_set?
69  I added this to my linkcmds. 
70
71[listing]
72----
73    /* sysinit section? */
74    . = ALIGN (16);
75    _bsd__start_set_sysinit_set = .;
76    *(set_sys_init_*);
77    _bsd__stop_set_sysinit_set = .;
78
79----
80
81* Convert all BSP linkcmds to use a linkcmds.base so the sections are
82easier to insert.
83
84* rtems-bsd-init-with-irq.c:
85  rtems_bsd_initialize_with_interrupt_server() has reference to
86    rtems_interrupt_server_initialize() and this method is unimplemented
87    - XXX BSP implements pieces
88    - BSPs using this software stack must support it apparently.
89    - What about Simple Vectored architectures?
90
91* maxproc variable referenced by rtems-bsd-resource.c.  What should it
92be set to?
93
94* ngroups_max variable referenced by rtems-bsd-prot.c.  - What should
95it be set to?
96
97== FreeBSD Source
98
99You should be able to rely on FreebSD manual pages and documentation
100for details on the code itself.
101
102=== Automatically Generated FreeBSD Files
103
104The FreeBSD source tarball includes a file named Makefile.rtems which
105has stanzas to automatically generate some files using awk. For details
106on this, see http://www.freebsd.org/cgi/man.cgi?query=kobj&apropos=0&sektion=0&manpath=FreeBSD+9.0-RELEASE&arch=default&format=html
107
108XXX This needs more detail.
109
110=== Rules for Modifying FreeBSD Source
111
112* Only add lines.  Subtract code by added "ifndef __rtems__". This makes
113merging easier in the future.
114
115== libbsd Source
116
117=== What is in git
118
119The git source is a self-contained kit with FreeBSD and RTEMS components
120pre-merged. The Makefile in this kit is automatically generated.
121
122Any changes to sources in the freebsd or contrib directories will need to
123be merged upstream into our master FreeBSD svn checkout.
124
125The FreeBSD sources managed in RTEMS libbsd git repository (e.g. contrib
126and freebsd directories) contain the "managed" version of the
127FreeBSD source.  The FreeBSD SVN source is the "master" version. The
128freebsd-to-rtems.py script is used to transfer files between the two
129trees. In general terms, if you have modified FreeBSD in the RTEMS libbsd
130tree, you want to run the script in "revert" or "reverse" mode to move
131the source back so you can run an "svn diff" against the upstream FreeBSD
132source. If you want to transfer source from the FreeBSD SVN checkout to
133the RTEMS libbsd tree, then you want to run the script in "forward" or
134default mode.
135
136=== Building RTEMS libbsd source
137
138You need to configure RTEMS for the desired BSP and install it. The
139following is the script used to build the powerpc/psim BSP for our
140internal testing purposes:
141
142[listing]
143----
144#! /bin/sh
145
146cd ${HOME}/newbsd
147rm -rf b-psim
148mkdir b-psim
149cd b-psim
150../git/rtems/configure --target=powerpc-rtems4.11 \
151  --enable-rtemsbsp=psim --disable-networking \
152  --enable-tests=samples \
153  --prefix=${HOME}/newbsd/bsp-install >c.log 2>&1 && \
154  make >b.log 2>&1 && \
155  make install >i.log 2>&1
156echo $?
157----
158
159Then edit the file config.inc to set RTEMS_MAKEFILE_PATH appropriately
160to indicate the ${prefix}/${target}/${BSP}.  Continuing on the above,
161the config.inc used to match the above is:
162
163[listing]
164----
165RTEMS_MAKEFILE_PATH = ${HOME}/newbsd/bsp-install/powerpc-rtems4.11/psim/
166INSTALL_BASE = ${HOME}/newbsd/install
167----
168
169The above installs the RTEMS libbsd kit into a separate place from
170RTEMS and the BSP. The RTEMS libbsd tests are built against an installed
171image of the RTEMS libbsd. By keeping it in a separate installation point
172from RTEMS itself, this makes it easier to remove a libbsd installation
173and have a clean test point.
174
175[listing]
176----
177make
178make install
179make -C testsuite
180----
181
182At this point, we expect multiple linker errors. That is what we are
183currently working on.
184
185=== Organization
186
187The top level directory contains a few directories and files. The following
188are important to understand:
189
190* freebsd-to-rtems.py - script to convert to and free FreeBSD and RTEMS trees
191* Makefile - automatically generated
192* contrib/ - from FreeBSD by script.
193* freebsd/ - from FreeBSD by script.
194* rtemsbsd/ - RTEMS specific implementations of FreeBSD kernel support routines.
195* testsuite/ - RTEMS specific tests
196* libbsd.txt - Documentation in Asciidoc
197
198== Moving Code Between FreeBSD SVN and RTEMS libbsd
199
200The script freebsd-to-rtems.py is used to copy code from FreeBSD to the
201RTEMS libbsd tree and to reverse this process. This script attempts to
202automate this process as much as possible and performs some transformations
203on the FreeBSD code. Its command line arguments are shown below:
204
205[listing]
206----
207freebsd-to-rtems.py [args]
208  -?|-h|--help     print this and exit
209  -d|--dry-run     run program but no modifications
210  -D|--diff        provide diff of files between trees
211  -e|--early-exit  evaluate arguments, print results, and exit
212  -m|--makefile    just generate Makefile
213  -R|--reverse     default FreeBSD -> RTEMS, reverse that
214  -r|--rtems       RTEMS directory
215  -f|--freebsd     FreeBSD directory
216  -v|--verbose     enable verbose output mode
217----
218
219In its default mode of operation, freebsd-to-rtems.py is used to copy code
220from FreeBSD to the RTEMS libbsd tree and perform transformations.  In forward
221mode, the script may be requested to just generate the Makefile.
222
223In "reverse mode", this script undoes those transformations and copies
224the source code back to the FreeBSD SVN tree. This allows us to do
225'svn diff', evaluate changes made by the RTEMS Project, and report changes
226back to FreeBSD upstream.
227
228In either mode, the script may be asked to perform a dry-run or be verbose.
229Also, in either mode, the script is also smart enough to avoid copying over
230files which have not changed. This means that the timestamps of files are
231not changed unless the contents change. The script will also report the
232number of files which changed. In verbose mode, the script will print
233the name of the files which are changed.
234
235The following is an example forward run with no changes.
236
237[listing]
238----
239$ ~/newbsd/git/libbsd-8.2/freebsd-to-rtems.py \
240    -r /home/joel/newbsd/git/libbsd-8.2 \
241    -f /home/joel/newbsd/libbsd/freebsd-8.2 -v
242Verbose:                yes
243Dry Run:                no
244Only Generate Makefile: no
245RTEMS Directory:        /home/joel/newbsd/git/libbsd-8.2
246FreeBSD Directory:      /home/joel/newbsd/libbsd/freebsd-8.2
247Direction:              forward
248Generating into /home/joel/newbsd/git/libbsd-8.2
2490 files were changed.
250----
251
252The script may also be used to generate a diff in either forward or reverse
253direction.
254
255== Initialization of RTEMS Libbsd
256
257The initialization of the RTEMS Libbsd is based on the FreeBSD SYSINIT
258infrastructure. This is simply because we are initializing a subset of
259FreeBSD. For details refer to http://www.freebsd.org/cgi/man.cgi?query=SYSINIT&sektion=9&apropos=0&manpath=FreeBSD+9-current
260
261The key to initializing a system is to ensure that the desired device
262drivers are explicitly pulled into the linked application. This plus
263linking against the Libsd library will pull in the necessary FreeBSD
264infrastructure. The SYSINIT structures are automatically built at link
265time and the various initialization routines will thus be executed in'
266the correct order.
267
268XXX This needs more details.
Note: See TracBrowser for help on using the repository browser.