source: rtems-libbsd/libbsd.txt @ 00ee241

4.115-freebsd-12freebsd-9.3
Last change on this file since 00ee241 was 00ee241, checked in by Joel Sherrill <joel.sherrill@…>, on Mar 27, 2012 at 6:51:45 PM

Add example on SYSCTL_NODE expansion for _bsd_sysctlnet_children

  • Property mode set to 100644
File size: 11.1 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* NIC Device Drivers
98- Only common NIC drivers have been included in the initial set. These do not
99include any system on chip or ISA drivers.
100- The ISA drivers require more BSD infrastructure to be addressed. This was
101outside the scope of the initial porting effort.
102
103== FreeBSD Source
104
105You should be able to rely on FreebSD manual pages and documentation
106for details on the code itself.
107
108=== Automatically Generated FreeBSD Files
109
110The FreeBSD source tarball includes a file named Makefile.rtems which
111has stanzas to automatically generate some files using awk. For details
112on this, see http://www.freebsd.org/cgi/man.cgi?query=kobj&apropos=0&sektion=0&manpath=FreeBSD+9.0-RELEASE&arch=default&format=html
113
114XXX This needs more detail.
115
116=== Rules for Modifying FreeBSD Source
117
118* Only add lines.  Subtract code by added "ifndef __rtems__". This makes
119merging easier in the future.
120
121== libbsd Source
122
123=== What is in git
124
125The git source is a self-contained kit with FreeBSD and RTEMS components
126pre-merged. The Makefile in this kit is automatically generated.
127
128Any changes to sources in the freebsd or contrib directories will need to
129be merged upstream into our master FreeBSD svn checkout.
130
131The FreeBSD sources managed in RTEMS libbsd git repository (e.g. contrib
132and freebsd directories) contain the "managed" version of the
133FreeBSD source.  The FreeBSD SVN source is the "master" version. The
134freebsd-to-rtems.py script is used to transfer files between the two
135trees. In general terms, if you have modified FreeBSD in the RTEMS libbsd
136tree, you want to run the script in "revert" or "reverse" mode to move
137the source back so you can run an "svn diff" against the upstream FreeBSD
138source. If you want to transfer source from the FreeBSD SVN checkout to
139the RTEMS libbsd tree, then you want to run the script in "forward" or
140default mode.
141
142=== Building RTEMS libbsd source
143
144You need to configure RTEMS for the desired BSP and install it. The
145following is the script used to build the powerpc/psim BSP for our
146internal testing purposes:
147
148[listing]
149----
150#! /bin/sh
151
152cd ${HOME}/newbsd
153rm -rf b-psim
154mkdir b-psim
155cd b-psim
156../git/rtems/configure --target=powerpc-rtems4.11 \
157  --enable-rtemsbsp=psim --disable-networking \
158  --enable-tests=samples \
159  --prefix=${HOME}/newbsd/bsp-install >c.log 2>&1 && \
160  make >b.log 2>&1 && \
161  make install >i.log 2>&1
162echo $?
163----
164
165Then edit the file config.inc to set RTEMS_MAKEFILE_PATH appropriately
166to indicate the ${prefix}/${target}/${BSP}.  Continuing on the above,
167the config.inc used to match the above is:
168
169[listing]
170----
171RTEMS_MAKEFILE_PATH = ${HOME}/newbsd/bsp-install/powerpc-rtems4.11/psim/
172INSTALL_BASE = ${HOME}/newbsd/install
173----
174
175The above installs the RTEMS libbsd kit into a separate place from
176RTEMS and the BSP. The RTEMS libbsd tests are built against an installed
177image of the RTEMS libbsd. By keeping it in a separate installation point
178from RTEMS itself, this makes it easier to remove a libbsd installation
179and have a clean test point.
180
181[listing]
182----
183make
184make install
185make -C testsuite
186----
187
188At this point, we expect multiple linker errors. That is what we are
189currently working on.
190
191=== Organization
192
193The top level directory contains a few directories and files. The following
194are important to understand:
195
196* freebsd-to-rtems.py - script to convert to and free FreeBSD and RTEMS trees
197* Makefile - automatically generated
198* contrib/ - from FreeBSD by script.
199* freebsd/ - from FreeBSD by script.
200* rtemsbsd/ - RTEMS specific implementations of FreeBSD kernel support routines.
201* testsuite/ - RTEMS specific tests
202* libbsd.txt - Documentation in Asciidoc
203
204== Moving Code Between FreeBSD SVN and RTEMS libbsd
205
206The script freebsd-to-rtems.py is used to copy code from FreeBSD to the
207RTEMS libbsd tree and to reverse this process. This script attempts to
208automate this process as much as possible and performs some transformations
209on the FreeBSD code. Its command line arguments are shown below:
210
211[listing]
212----
213freebsd-to-rtems.py [args]
214  -?|-h|--help     print this and exit
215  -d|--dry-run     run program but no modifications
216  -D|--diff        provide diff of files between trees
217  -e|--early-exit  evaluate arguments, print results, and exit
218  -m|--makefile    just generate Makefile
219  -R|--reverse     default FreeBSD -> RTEMS, reverse that
220  -r|--rtems       RTEMS directory
221  -f|--freebsd     FreeBSD directory
222  -v|--verbose     enable verbose output mode
223----
224
225In its default mode of operation, freebsd-to-rtems.py is used to copy code
226from FreeBSD to the RTEMS libbsd tree and perform transformations.  In forward
227mode, the script may be requested to just generate the Makefile.
228
229In "reverse mode", this script undoes those transformations and copies
230the source code back to the FreeBSD SVN tree. This allows us to do
231'svn diff', evaluate changes made by the RTEMS Project, and report changes
232back to FreeBSD upstream.
233
234In either mode, the script may be asked to perform a dry-run or be verbose.
235Also, in either mode, the script is also smart enough to avoid copying over
236files which have not changed. This means that the timestamps of files are
237not changed unless the contents change. The script will also report the
238number of files which changed. In verbose mode, the script will print
239the name of the files which are changed.
240
241The following is an example forward run with no changes.
242
243[listing]
244----
245$ ~/newbsd/git/libbsd-8.2/freebsd-to-rtems.py \
246    -r /home/joel/newbsd/git/libbsd-8.2 \
247    -f /home/joel/newbsd/libbsd/freebsd-8.2 -v
248Verbose:                yes
249Dry Run:                no
250Only Generate Makefile: no
251RTEMS Directory:        /home/joel/newbsd/git/libbsd-8.2
252FreeBSD Directory:      /home/joel/newbsd/libbsd/freebsd-8.2
253Direction:              forward
254Generating into /home/joel/newbsd/git/libbsd-8.2
2550 files were changed.
256----
257
258The script may also be used to generate a diff in either forward or reverse
259direction.
260
261== Initialization of RTEMS Libbsd
262
263The initialization of the RTEMS Libbsd is based on the FreeBSD SYSINIT
264infrastructure. This is simply because we are initializing a subset of
265FreeBSD. For details refer to http://www.freebsd.org/cgi/man.cgi?query=SYSINIT&sektion=9&apropos=0&manpath=FreeBSD+9-current
266
267The key to initializing a system is to ensure that the desired device
268drivers are explicitly pulled into the linked application. This plus
269linking against the Libsd library will pull in the necessary FreeBSD
270infrastructure. The SYSINIT structures are automatically built at link
271time and the various initialization routines will thus be executed in'
272the correct order.
273
274XXX This needs more details.
275
276=== SYSCTL_NODE Example
277
278During development, we had an undefined reference to
279_bsd_sysctl__net_children that we had trouble tracking down. Thanks to
280Chris Johns, we located it. He explained how to read SYSCTL_NODE
281definitions. This line from freebsd/netinet/in_proto.c is attempting
282to add the "inet" node to the parent node "_net".
283
284[listing]
285----
286SYSCTL_NODE(_net,      PF_INET,         inet,   CTLFLAG_RW, 0,
287        "Internet Family");
288----
289
290Our problem was that we could not find where _bsd_sysctl__net_children
291was defined. Chris suggested that when in doubt compile with -save-temps
292and look at the preprocessed .i files. But he did not need that. He
293explained that this the symbol name _bsd_sysctl__net_children was
294automatically generated by a SYSCTL_NODE as follows:
295
296* _bsd_ - added by RTEMS modifications to SYSCTL_NODE macro
297* sysctl_ - boilerplace added by SYSCTL_NODE macro
298* "" - empty string for parent node
299* net - name of SYSCTL_NODE
300* children - added by SYSCTL macros
301 
302This was all generated by a support macro declaring the node as this:
303
304[listing]
305----
306struct sysctl_oid_list SYSCTL_NODE_CHILDREN(parent, name);
307----
308
309Given this information, we located this SYSCTL_NODE declaration in
310kern/kern_mib.c
311
312[listing]
313----
314SYSCTL_NODE(, CTL_KERN,   kern,   CTLFLAG_RW, 0,
315        "High kernel, proc, limits &c");
316----
317
Note: See TracBrowser for help on using the repository browser.