source: rtems-libbsd/libbsd.txt @ 455aa3a

4.115-freebsd-12freebsd-9.3
Last change on this file since 455aa3a was 455aa3a, checked in by Joel Sherrill <joel.sherrill@…>, on Mar 9, 2012 at 7:04:44 PM

Add more details to documentation.

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