source: rtems-libbsd/libbsd.txt @ da96928

4.115-freebsd-12freebsd-9.3
Last change on this file since da96928 was da96928, checked in by Sebastian Huber <sebastian.huber@…>, on May 16, 2014 at 11:04:35 AM

doc: Clarify linkcmds sections

  • Property mode set to 100644
File size: 34.4 KB
Line 
1RTEMS BSD Library Guide
2=======================
3:toc:
4:icons:
5:numbered:
6:website: http://www.rtems.org/
7
8RTEMS uses FreeBSD 9.2 as the source of its TCP/IP and USB stacks.
9This is a guide which captures information on the
10process of merging code from FreeBSD, building this library,
11RTEMS specific support files, and general guidelines on what
12modifications to the FreeBSD source are permitted.
13
14Goals of this effort are
15
16* update TCP/IP and provide USB in RTEMS,
17* ease updating to future FreeBSD versions,
18* ease tracking changes in FreeBSD code,
19* minimize manual changes in FreeBSD code, and
20* define stable kernel/device driver API which is implemented
21by both RTEMS and FreeBSD. This is the foundation of the port.
22
23We will work to push our changes upstream to the FreeBSD Project
24and minimize changes required at each update point.
25
26*******************************************************************************
27This is a work in progress and is very likely to be incomplete.
28Please help by adding to it.
29*******************************************************************************
30
31== Getting Started
32
33=== Tool Chain ===
34
35You need a tool chain for RTEMS based on at least
36
37* Binutils 2.24, and
38* Newlib 2.1.0.
39
40The Binutils version is required to ease the handling of linker command files.
41The Newlib version is required since some standard files like `<sys/types.h>`
42must be compatible enough for the files provided by the FreeBSD sources, e.g.
43`<sys/socket.h>`.
44
45=== Installation Overview ===
46
47. You must configure your BSP with the +--disable-networking+ option to disable
48the old network stack.  Make sure no header files of the old network stack are
49installed.
50. Clone the Git repository +git clone git://git.rtems.org/rtems-libbsd.git+.
51. Change into the RTEMS BSD library root directory.
52. Edit the 'config.inc' Makefile configuration file and adjust it to your environment.
53. Run +make clean+.
54. Run +make install+.
55
56=== Board Support Package Requirements ===
57
58The RTEMS version must be at least 4.11.  The Board Support Package (BSP)
59should support the
60http://www.rtems.org/onlinedocs/doxygen/cpukit/html/group\__rtems\__interrupt__extension.html[Interrupt Manager Extension]
61// The first underscores have to be masked to stop asciidoc interpreting them
62to make use of generic FreeBSD based drivers.
63
64The linker command file of the BSP must contain the following section
65definitions:
66
67-------------------------------------------------------------------------------
68.rtemsroset : {
69        KEEP (*(SORT(.rtemsroset.*)))
70}
71
72.rtemsrwset : {
73        KEEP (*(SORT(.rtemsrwset.*)))
74}
75-------------------------------------------------------------------------------
76
77The first output section can be placed in read-only memory.  The second output
78section must be placed in read-write memory.  The output section name is not
79relevant.  The output sections may also contain other input sections.
80
81=== Board Support Package Configuration and Build ===
82
83You need to configure RTEMS for the desired BSP and install it.  The BSP should
84be configured with a disabled network stack.  The BSD library containing the
85new network stack is a separate package.  Using a BSP installation containing
86the old network stack may lead to confusion and unpredictable results.
87
88The following script is used to build the `arm/realview_pbx_a9_qemu` BSP for
89our internal testing purposes:
90
91-------------------------------------------------------------------------------
92#!/bin/sh
93
94cd ${HOME}/sandbox
95rm -rf b-realview_pbx_a9_qemu
96mkdir b-realview_pbx_a9_qemu
97cd b-realview_pbx_a9_qemu
98${HOME}/git-rtems/configure \
99        --prefix=${HOME}/sandbox/install \
100        --target=arm-rtems4.11 \
101        --enable-rtemsbsp=realview_pbx_a9_qemu \
102        --disable-networking && \
103        make && \
104        make install
105-------------------------------------------------------------------------------
106
107The `arm/realview_pbx_a9_qemu` BSP running on the Qemu simulator has some
108benefits for development and test of the BSD library
109
110* it offers a NULL pointer read and write protection,
111* Qemu is a fast simulator,
112* Qemu provides support for GDB watchpoints,
113* Qemu provides support for virtual Ethernet networks, e.g. TUN and bridge
114devices (you can run multiple test instances on one virtual network).
115
116=== BSD Library Configuration and Build ===
117
118In the BSD library source directory edit the file 'config.inc'.  Continuing on
119the above, the 'config.inc' used to match the above is:
120
121-------------------------------------------------------------------------------
122# Mandatory: Select your BSP and installation prefix
123TARGET = arm-rtems4.11
124BSP = realview_pbx_a9_qemu
125PREFIX = $(HOME)/sandbox/install
126
127# Optional: Separate installation base directory
128INSTALL_BASE = $(PREFIX)/$(TARGET)/$(BSP)
129
130# Optional: Network test configuration
131TEST_RUNNER = $(BSP)
132NET_CFG_SELF_IP = 10.0.0.2
133NET_CFG_NETMASK = 255.255.0.0
134NET_CFG_PEER_IP = 10.0.0.1
135NET_CFG_GATEWAY_IP = 10.0.0.1
136NET_TAP_INTERFACE = tap0
137-------------------------------------------------------------------------------
138
139Now you can build the BSD library and run the tests:
140
141-------------------------------------------------------------------------------
142make clean
143make
144make run_tests
145-------------------------------------------------------------------------------
146
147To install the BSD library use this:
148
149-------------------------------------------------------------------------------
150make install
151-------------------------------------------------------------------------------
152
153=== BSD Library Initialization ===
154
155Use the following code to initialize the BSD library:
156
157-------------------------------------------------------------------------------
158#include <assert.h>
159
160#include <rtems/bsd/bsd.h>
161
162void do_init(void)
163{
164        rtems_status_code sc;
165
166        sc = rtems_bsd_initialize();
167        assert(sc == RTEMS_SUCCESSFUL);
168}
169-------------------------------------------------------------------------------
170
171== Network Stack Features
172
173http://roy.marples.name/projects/dhcpcd/index[DHCPCD(8)]:: DHCP client
174
175https://developer.apple.com/library/mac/documentation/Networking/Reference/DNSServiceDiscovery_CRef/Reference/reference.html[dns_sd.h]:: DNS Service Discovery
176
177http://www.opensource.apple.com/source/mDNSResponder/mDNSResponder-320.10/mDNSCore/mDNSEmbeddedAPI.h[mDNS]:: Multi-Cast DNS
178
179http://www.freebsd.org/cgi/man.cgi?query=unix&sektion=4&apropos=0&manpath=FreeBSD+9.2-RELEASE[UNIX(4)]:: UNIX-domain protocol family
180
181http://www.freebsd.org/cgi/man.cgi?query=inet&sektion=4&apropos=0&manpath=FreeBSD+9.2-RELEASE[INET(4)]:: Internet protocol family
182
183http://www.freebsd.org/cgi/man.cgi?query=inet6&apropos=0&sektion=4&manpath=FreeBSD+9.2-RELEASE&arch=default&format=html[INET6(4)]:: Internet protocol version 6 family
184
185http://www.freebsd.org/cgi/man.cgi?query=tcp&apropos=0&sektion=4&manpath=FreeBSD+9.2-RELEASE&arch=default&format=html[TCP(4)]:: Internet Transmission Control Protocol
186
187http://www.freebsd.org/cgi/man.cgi?query=udp&apropos=0&sektion=4&manpath=FreeBSD+9.2-RELEASE&arch=default&format=html[UDP(4)]:: Internet User Datagram Protocol
188
189http://www.freebsd.org/cgi/man.cgi?query=route&sektion=4&apropos=0&manpath=FreeBSD+9.2-RELEASE[ROUTE(4)]:: Kernel packet forwarding database
190
191http://www.freebsd.org/cgi/man.cgi?query=bpf&apropos=0&sektion=4&manpath=FreeBSD+9.2-RELEASE&arch=default&format=html[BPF(4)]:: Berkeley Packet Filter
192
193http://www.freebsd.org/cgi/man.cgi?query=socket&apropos=0&sektion=2&manpath=FreeBSD+9.2-RELEASE&arch=default&format=html[SOCKET(2)]:: Create an endpoint for communication
194
195http://www.freebsd.org/cgi/man.cgi?query=kqueue&apropos=0&sektion=2&manpath=FreeBSD+9.2-RELEASE&arch=default&format=html[KQUEUE(2)]:: Kernel event notification mechanism
196
197http://www.freebsd.org/cgi/man.cgi?query=select&apropos=0&sektion=2&manpath=FreeBSD+9.2-RELEASE&arch=default&format=html[SELECT(2)]:: Synchronous I/O multiplexing
198
199http://www.freebsd.org/cgi/man.cgi?query=poll&apropos=0&sektion=2&manpath=FreeBSD+9.2-RELEASE&arch=default&format=html[POLL(2)]:: Synchronous I/O multiplexing
200
201http://www.freebsd.org/cgi/man.cgi?query=route&apropos=0&sektion=8&manpath=FreeBSD+9.2-RELEASE&arch=default&format=html[ROUTE(8)]:: Manually manipulate the routing tables
202
203http://www.freebsd.org/cgi/man.cgi?query=ifconfig&apropos=0&sektion=8&manpath=FreeBSD+9.2-RELEASE&arch=default&format=html[IFCONFIG(8)]:: Configure network interface parameters
204
205http://www.freebsd.org/cgi/man.cgi?query=netstat&apropos=0&sektion=1&manpath=FreeBSD+9.2-RELEASE&arch=default&format=html[NETSTAT(1)]:: Show network status
206
207http://www.freebsd.org/cgi/man.cgi?query=ping&apropos=0&sektion=8&manpath=FreeBSD+9.2-RELEASE&arch=default&format=html[PING(8)]:: Send ICMP ECHO_REQUEST packets to network hosts
208
209http://www.freebsd.org/cgi/man.cgi?query=ping6&apropos=0&sektion=8&manpath=FreeBSD+9.2-RELEASE&arch=default&format=html[PING6(8)]:: Send ICMPv6 ECHO_REQUEST packets to network hosts
210
211http://www.freebsd.org/cgi/man.cgi?query=sysctl&sektion=3&apropos=0&manpath=FreeBSD+9.2-RELEASE[SYSCTL(3)]:: Get or set system information
212
213http://www.freebsd.org/cgi/man.cgi?query=resolver&sektion=3&apropos=0&manpath=FreeBSD+9.2-RELEASE[RESOLVER(3)]:: Resolver routines
214
215http://www.freebsd.org/cgi/man.cgi?query=gethostbyname&sektion=3&apropos=0&manpath=FreeBSD+9.2-RELEASE[GETHOSTBYNAME(3)]:: Get network host entry
216
217== Issues and TODO
218
219* Per-CPU data should be enabled once the new stack is ready for SMP.
220
221* Per-CPU NETISR(9) should be enabled onece the new stack is ready for SMP.
222
223* Multiple routing tables are not supported.  Every FIB value is set to zero
224  (= BSD_DEFAULT_FIB).
225
226* Process identifiers are not supported.  Every PID value is set to zero
227  (= BSD_DEFAULT_PID).
228
229* User credentials are not supported.  The following functions allow the
230  operation for everyone
231  - prison_equal_ip4(),
232  - chgsbsize(),
233  - cr_cansee(),
234  - cr_canseesocket() and
235  - cr_canseeinpcb().
236
237* A basic USB functionality test that is known to work on Qemu is desirable.
238
239* Adapt generic IRQ PIC interface code to Simple Vectored Interrupt Model
240  so that those architectures can use new TCP/IP and USB code.
241
242* freebsd-userspace/rtems/include/sys/syslog.h is a copy from the old
243  RTEMS TCP/IP stack. For some reason, the __printflike markers do not
244  compile in this environment. We may want to use the FreeBSD syslog.h
245  and get this addressed.
246
247* in_cksum implementations for architectures not supported by FreeBSD.
248  This will require figuring out where to put implementations that do
249  not originate from FreeBSD and are populated via the script.
250
251* MAC support functions are not thread-safe ("freebsd/lib/libc/posix1e/mac.c").
252
253* IFCONFIG(8): IEEE80211 support is disabled.  This module depends on a XML
254  parser and mmap().
255
256* get_cyclecount(): The implementation is a security problem.
257
258* What to do with the priority parameter present in the FreeBSD synchronization
259  primitives and the thread creation functions?
260
261* TASKQUEUE(9): Support spin mutexes.
262
263* ZONE(9): Review allocator lock usage in rtems-bsd-chunk.c.
264
265* KQUEUE(2): Choose proper lock for global kqueue list.
266
267* TIMEOUT(9): Maybe use special task instead of timer server to call
268  callout_tick().
269
270* sysctl_handle_opaque(): Implement reliable snapshots.
271
272* PING6(8): What to do with SIGALARM?
273
274* <sys/param.h>: Update Newlib to use a MSIZE of 256.
275
276* BPF(4): Add support for zero-copy buffers.
277
278* UNIX(4): Fix race conditions in the area of socket object and file node
279  destruction.  Add support for file descriptor transmission via control
280  messages.
281
282* PRINTF(9): Add support for log(), the %D format specifier is missing in the
283  normal printf() family.
284
285* Why is the interrupt server used?  The BSD interrupt handlers can block on
286synchronization primitives like mutexes.  This is in contrast to RTEMS
287interrupt service routines.  The BSPs using the generic interrupt support must
288implement the `bsp_interrupt_vector_enable()` and
289`bsp_interrupt_vector_disable()` routines.  They normally enable/disable a
290particular interrupt source at the interrupt controller.  This can be used to
291implement the interrupt server.  The interrupt server is a task that wakes-up
292in case an associated interrupt happens.  The interrupt source is disabled in
293a generic interrupt handler that wakes-up the interrupt server task.   Once the
294postponed interrupt processing is performed in the interrupt server the
295interrupt source is enabled again.
296
297* Convert all BSP linkcmds to use a linkcmds.base so the sections are
298easier to insert.
299
300* NIC Device Drivers
301- Only common PCI NIC drivers have been included in the initial set. These
302do not include any system on chip or ISA drivers.
303- PCI configuration probe does not appear to happen to determine if a
304NIC is in I/O or memory space. We have worked around this by using a
305static hint to tell the fxp driver the correct mode. But this needs to
306be addressed.
307- The ISA drivers require more BSD infrastructure to be addressed. This was
308outside the scope of the initial porting effort.
309
310== FreeBSD Source
311
312You should be able to rely on FreebSD manual pages and documentation
313for details on the code itself.
314
315=== Automatically Generated FreeBSD Files
316
317Some source and header files are automatically generated during the FreeBSD
318build process.  The `Makefile.todo` file performs this manually.  The should be
319included in `freebsd-to-rtems.py` script some time in the future.  For details,
320see also
321http://www.freebsd.org/cgi/man.cgi?query=kobj&sektion=9&apropos=0&manpath=FreeBSD+9.2-RELEASE[KOBJ(9)].
322
323=== Rules for Modifying FreeBSD Source
324
325Only add lines.  Subtract code by added `#ifndef __rtems__`.  This makes
326merging easier in the future.  For example:
327
328-------------------------------------------------------------------------------
329/* Global variables for the kernel. */
330
331#ifndef __rtems__
332/* 1.1 */
333extern char kernelname[MAXPATHLEN];
334#endif /* __rtems__ */
335
336extern int tick;                        /* usec per tick (1000000 / hz) */
337-------------------------------------------------------------------------------
338
339-------------------------------------------------------------------------------
340#if defined(_KERNEL) || defined(_WANT_FILE)
341#ifdef __rtems__
342#include <rtems/libio_.h>
343#include <sys/fcntl.h>
344#endif /* __rtems__ */
345/*
346 * Kernel descriptor table.
347 * One entry for each open kernel vnode and socket.
348 *
349 * Below is the list of locks that protects members in struct file.
350 *
351 * (f) protected with mtx_lock(mtx_pool_find(fp))
352 * (d) cdevpriv_mtx
353 * none not locked
354 */
355-------------------------------------------------------------------------------
356
357-------------------------------------------------------------------------------
358extern int profprocs;                   /* number of process's profiling */
359#ifndef __rtems__
360extern volatile int ticks;
361#else /* __rtems__ */
362#include <rtems/score/watchdogimpl.h>
363#define ticks _Watchdog_Ticks_since_boot
364#endif /* __rtems__ */
365
366#endif /* _KERNEL */
367-------------------------------------------------------------------------------
368
369Add nothing (even blank lines) before or after the `__rtems__` guards.  Always
370include a `__rtems__` in the guards to make searches easy.
371
372== BSD Library Source
373
374=== What is in the Git Repository
375
376There is a self-contained kit with FreeBSD and RTEMS components pre-merged. The
377Makefile in this kit is automatically generated.
378
379Any changes to source in the `freebsd` directories will need to be merged
380upstream into our master FreeBSD checkout, the `freebsd-org` submodule.
381
382The repository contains two FreeBSD source trees.  In the `freebsd` directory
383are the so called 'managed' FreeBSD sources used to build the BSD library.  The
384FreeBSD source in `freebsd-org` is the 'master' version.  The
385`freebsd-to-rtems.py` script is used to transfer files between the two trees.
386In general terms, if you have modified managed FreeBSD sources, you will need
387to run the script in 'revert' or 'reverse' mode using the `-R` switch.  This
388will copy the source back to your local copy of the master FreeBSD source so
389you can run `git diff` against the upstream FreeBSD source.  If you want to
390transfer source files from the master FreeBSD source to the manged FreeBSD
391sources, then you must run the script in 'forward' mode (the default).
392
393=== Organization
394
395The top level directory contains a few directories and files. The following
396are important to understand
397
398* `freebsd-to-rtems.py` - script to convert to and free FreeBSD and RTEMS trees,
399* `Makefile` - automatically generated,
400* `freebsd/` - from FreeBSD by script,
401* `rtemsbsd/` - RTEMS specific implementations of FreeBSD kernel support routines,
402* `testsuite/` - RTEMS specific tests, and
403* `libbsd.txt` - documentation in Asciidoc.
404
405== Moving Code Between Managed and Master FreeBSD Source
406
407The script `freebsd-to-rtems.py` is used to copy code from FreeBSD to the
408rtems-libbsd tree and to reverse this process. This script attempts to
409automate this process as much as possible and performs some transformations
410on the FreeBSD code. Its command line arguments are shown below:
411
412----
413freebsd-to-rtems.py [args]
414  -?|-h|--help     print this and exit
415  -d|--dry-run     run program but no modifications
416  -D|--diff        provide diff of files between trees
417  -e|--early-exit  evaluate arguments, print results, and exit
418  -m|--makefile    just generate Makefile
419  -R|--reverse     default FreeBSD -> RTEMS, reverse that
420  -r|--rtems       RTEMS directory
421  -f|--freebsd     FreeBSD directory
422  -v|--verbose     enable verbose output mode
423----
424
425In its default mode of operation, freebsd-to-rtems.py is used to copy code
426from FreeBSD to the rtems-libbsd tree and perform transformations.  In forward
427mode, the script may be requested to just generate the Makefile.
428
429In "reverse mode", this script undoes those transformations and copies
430the source code back to the FreeBSD SVN tree. This allows us to do
431'svn diff', evaluate changes made by the RTEMS Project, and report changes
432back to FreeBSD upstream.
433
434In either mode, the script may be asked to perform a dry-run or be verbose.
435Also, in either mode, the script is also smart enough to avoid copying over
436files which have not changed. This means that the timestamps of files are
437not changed unless the contents change. The script will also report the
438number of files which changed. In verbose mode, the script will print
439the name of the files which are changed.
440
441The following is an example forward run with no changes.
442
443----
444$ ~/newbsd/git/libbsd-8.2/freebsd-to-rtems.py \
445    -r /home/joel/newbsd/git/libbsd-8.2 \
446    -f /home/joel/newbsd/libbsd/freebsd-8.2 -v
447Verbose:                yes
448Dry Run:                no
449Only Generate Makefile: no
450RTEMS Directory:        /home/joel/newbsd/git/libbsd-8.2
451FreeBSD Directory:      /home/joel/newbsd/libbsd/freebsd-8.2
452Direction:              forward
453Generating into /home/joel/newbsd/git/libbsd-8.2
4540 files were changed.
455----
456
457The script may also be used to generate a diff in either forward or reverse
458direction.
459
460== Initialization of the BSD Library
461
462The initialization of the BSD library is based on the FreeBSD SYSINIT(9)
463infrastructure.  The key to initializing a system is to ensure that the desired
464device drivers are explicitly pulled into the linked application.  This plus
465linking against the BSD library (`libbsd.a`) will pull in the necessary FreeBSD
466infrastructure.
467
468The FreeBSD kernel is not a library like the RTEMS kernel.  It is a bunch of
469object files linked together.  If we have a library, then creating the
470executable is simple.  We begin with a start symbol and recursively resolve all
471references.  With a bunch of object files linked together we need a different
472mechanism.  Most object files don't know each other.  Lets say we have a driver
473module.  The rest of the system has no references to this driver module.  The
474driver module needs a way to tell the rest of the system: Hey, kernel I am
475here, please use my services!
476
477This registration of independent components is performed by SYSINIT(9) and
478specializations:
479
480http://www.freebsd.org/cgi/man.cgi?query=SYSINIT
481
482The SYSINIT(9) uses some global data structures that are placed in a certain
483section.  In the linker command file we need this:
484
485-------------------------------------------------------------------------------
486.rtemsroset : {
487        KEEP (*(SORT(.rtemsroset.*)))
488}
489
490.rtemsrwset : {
491        KEEP (*(SORT(.rtemsrwset.*)))
492}
493-------------------------------------------------------------------------------
494
495This results for example in this executable layout:
496
497-------------------------------------------------------------------------------
498[...]
499 *(SORT(.rtemsroset.*))
500 .rtemsroset.bsd.modmetadata_set.begin
501                0x000000000025fe00        0x0 libbsd.a(rtems-bsd-init.o)
502                0x000000000025fe00                _bsd__start_set_modmetadata_set
503 .rtemsroset.bsd.modmetadata_set.content
504                0x000000000025fe00        0x8 libbsd.a(rtems-bsd-nexus.o)
505 .rtemsroset.bsd.modmetadata_set.content
506                0x000000000025fe08        0x4 libbsd.a(kern_module.o)
507[...]
508 .rtemsroset.bsd.modmetadata_set.content
509                0x000000000025fe68        0x4 libbsd.a(mii.o)
510 .rtemsroset.bsd.modmetadata_set.content
511                0x000000000025fe6c        0x4 libbsd.a(mii_bitbang.o)
512 .rtemsroset.bsd.modmetadata_set.end
513                0x000000000025fe70        0x0 libbsd.a(rtems-bsd-init.o)
514                0x000000000025fe70                _bsd__stop_set_modmetadata_set
515[...]
516.rtemsrwset     0x000000000030bad0      0x290
517 *(SORT(.rtemsrwset.*))
518 .rtemsrwset.bsd.sysinit_set.begin
519                0x000000000030bad0        0x0 libbsd.a(rtems-bsd-init.o)
520                0x000000000030bad0                _bsd__start_set_sysinit_set
521 .rtemsrwset.bsd.sysinit_set.content
522                0x000000000030bad0        0x4 libbsd.a(rtems-bsd-nexus.o)
523 .rtemsrwset.bsd.sysinit_set.content
524                0x000000000030bad4        0x8 libbsd.a(rtems-bsd-thread.o)
525 .rtemsrwset.bsd.sysinit_set.content
526                0x000000000030badc        0x4 libbsd.a(init_main.o)
527[...]
528 .rtemsrwset.bsd.sysinit_set.content
529                0x000000000030bd54        0x4 libbsd.a(frag6.o)
530 .rtemsrwset.bsd.sysinit_set.content
531                0x000000000030bd58        0x8 libbsd.a(uipc_accf.o)
532 .rtemsrwset.bsd.sysinit_set.end
533                0x000000000030bd60        0x0 libbsd.a(rtems-bsd-init.o)
534                0x000000000030bd60                _bsd__stop_set_sysinit_set
535[...]
536-------------------------------------------------------------------------------
537
538Here you can see, that some global data structures are collected into
539continuous memory areas.  This memory area can be identified by start and stop
540symbols.  This constructs a table of uniform items.
541
542The low level FreeBSD code calls at some time during the initialization the
543mi_startup() function (machine independent startup).  This function will sort
544the SYSINIT(9) set and call handler functions which perform further
545initialization.  The last step is the scheduler invocation.
546
547The SYSINIT(9) routines are run in mi_startup() which is called by
548rtems_bsd_initialize().
549
550This is also explained in "The Design and Implementation of the FreeBSD
551Operating System" section 14.3 "Kernel Initialization".
552
553In RTEMS we have a library and not a bunch of object files.  Thus we need a way
554to pull-in the desired services out of the libbsd.  Here the
555`rtems-bsd-sysinit.h` comes into play.  The SYSINIT(9) macros have been
556modified and extended for RTEMS in `<sys/kernel.h>`:
557
558-------------------------------------------------------------------------------
559#ifndef __rtems__
560#define C_SYSINIT(uniquifier, subsystem, order, func, ident)    \
561        static struct sysinit uniquifier ## _sys_init = {       \
562                subsystem,                                      \
563                order,                                          \
564                func,                                           \
565                (ident)                                         \
566        };                                                      \
567        DATA_SET(sysinit_set,uniquifier ## _sys_init)
568#else /* __rtems__ */
569#define SYSINIT_ENTRY_NAME(uniquifier)                          \
570        _bsd_ ## uniquifier ## _sys_init
571#define SYSINIT_REFERENCE_NAME(uniquifier)                      \
572        _bsd_ ## uniquifier ## _sys_init_ref
573#define C_SYSINIT(uniquifier, subsystem, order, func, ident)    \
574        struct sysinit SYSINIT_ENTRY_NAME(uniquifier) = {       \
575                subsystem,                                      \
576                order,                                          \
577                func,                                           \
578                (ident)                                         \
579        };                                                      \
580        RWDATA_SET(sysinit_set,SYSINIT_ENTRY_NAME(uniquifier))
581#define SYSINIT_REFERENCE(uniquifier)                           \
582        extern struct sysinit SYSINIT_ENTRY_NAME(uniquifier);   \
583        static struct sysinit const * const                     \
584        SYSINIT_REFERENCE_NAME(uniquifier) __used               \
585        = &SYSINIT_ENTRY_NAME(uniquifier)
586#define SYSINIT_MODULE_REFERENCE(mod)                           \
587        SYSINIT_REFERENCE(mod ## module)
588#define SYSINIT_DRIVER_REFERENCE(driver, bus)                   \
589        SYSINIT_MODULE_REFERENCE(driver ## _ ## bus)
590#define SYSINIT_DOMAIN_REFERENCE(dom)                           \
591        SYSINIT_REFERENCE(domain_add_ ## dom)
592#endif /* __rtems__ */
593-------------------------------------------------------------------------------
594
595Here you see that the SYSINIT(9) entries are no longer static.  The
596\*_REFERENCE() macros will create references to the corresponding modules which
597are later resolved by the linker.  The application has to provide an object
598file with references to all required FreeBSD modules.
599
600The FreeBSD device model is quite elaborated (with follow-ups):
601
602http://www.freebsd.org/cgi/man.cgi?query=driver
603
604The devices form a tree with the Nexus device at a high-level.  This Nexus
605device is architecture specific in FreeBSD.  In RTEMS we have our own Nexus
606device, see `rtemsbsd/bsp/bsp-bsd-nexus-devices.c`.
607
608=== SYSCTL_NODE Example
609
610During development, we had an undefined reference to
611_bsd_sysctl__net_children that we had trouble tracking down. Thanks to
612Chris Johns, we located it. He explained how to read SYSCTL_NODE
613definitions. This line from freebsd/netinet/in_proto.c is attempting
614to add the "inet" node to the parent node "_net".
615
616----
617SYSCTL_NODE(_net,      PF_INET,         inet,   CTLFLAG_RW, 0,
618        "Internet Family");
619----
620
621Our problem was that we could not find where _bsd_sysctl__net_children
622was defined. Chris suggested that when in doubt compile with -save-temps
623and look at the preprocessed .i files. But he did not need that. He
624explained that this the symbol name _bsd_sysctl__net_children was
625automatically generated by a SYSCTL_NODE as follows:
626
627* _bsd_ - added by RTEMS modifications to SYSCTL_NODE macro
628* sysctl_ - boilerplace added by SYSCTL_NODE macro
629* "" - empty string for parent node
630* net - name of SYSCTL_NODE
631* children - added by SYSCTL macros
632 
633This was all generated by a support macro declaring the node as this:
634
635----
636struct sysctl_oid_list SYSCTL_NODE_CHILDREN(parent, name);
637----
638
639Given this information, we located this SYSCTL_NODE declaration in
640kern/kern_mib.c
641
642----
643SYSCTL_NODE(, CTL_KERN,   kern,   CTLFLAG_RW, 0,
644        "High kernel, proc, limits &c");
645----
646
647== Core FreeBSD APIs and RTEMS Replacements ==
648
649=== SX(9) (Shared/exclusive locks) ===
650
651http://www.freebsd.org/cgi/man.cgi?query=sx
652
653Binary semaphores (this neglects the ability to allow shared access).
654
655=== MUTEX(9) (Mutual exclusion) ===
656
657http://www.freebsd.org/cgi/man.cgi?query=mutex
658
659Binary semaphores (not recursive mutexes are not supported this way).
660
661=== RWLOCK(9) (Reader/writer lock) ===
662
663http://www.freebsd.org/cgi/man.cgi?query=rwlock
664
665POSIX r/w lock.
666
667=== RMLOCK(9) (Reader/writer lock optimized for mostly read access patterns) ===
668
669Note:  This object was implemented as a wrapper for RWLOCK in the rm_lock header file.
670
671http://www.freebsd.org/cgi/man.cgi?query=rmlock
672
673POSIX r/w lock.
674
675=== CONDVAR(9) (Condition variables) ===
676
677http://www.freebsd.org/cgi/man.cgi?query=condvar
678
679POSIX condition variables with modifications (hack).
680
681=== CALLOUT(9) (Timer functions) ===
682
683http://www.freebsd.org/cgi/man.cgi?query=callout
684
685Timer server.
686
687=== TASKQUEUE(9) (Asynchronous task execution) ===
688
689http://www.freebsd.org/cgi/man.cgi?query=taskqueue
690
691TBD.
692
693=== KTHREAD(9), KPROC(9) (Tasks) ===
694
695http://www.freebsd.org/cgi/man.cgi?query=kthread
696
697http://www.freebsd.org/cgi/man.cgi?query=kproc
698
699Tasks.
700
701=== ZONE(9) (Zone allocator) ===
702
703http://www.freebsd.org/cgi/man.cgi?query=zone
704
705TBD.
706
707=== devfs (Device file system) ===
708
709Dummy, IMFS or new implementation (currently dummy).
710
711=== psignal (Signals) ===
712
713TBD.  Seems to be not needed.
714
715=== poll, select ===
716
717TBD.  Seems to be not needed.
718
719=== RMAN(9) (Resource management) ===
720
721http://www.freebsd.org/cgi/man.cgi?query=rman
722
723TBD.  Seems to be not needed.
724
725=== DEVCLASS(9), DEVICE(9), DRIVER(9), MAKE_DEV(9) (Device management) ===
726
727http://www.freebsd.org/cgi/man.cgi?query=devclass
728
729http://www.freebsd.org/cgi/man.cgi?query=device
730
731http://www.freebsd.org/cgi/man.cgi?query=driver
732
733http://www.freebsd.org/cgi/man.cgi?query=make_dev
734
735Use FreeBSD implementation as far as possible.  FreeBSD has a nice API for
736dynamic device handling.  It may be interesting for RTEMS to use this API
737internally in the future.
738
739=== BUS_SPACE(9), BUS_DMA(9) (Bus and DMA access) ===
740
741http://www.freebsd.org/cgi/man.cgi?query=bus_space
742
743http://www.freebsd.org/cgi/man.cgi?query=bus_dma
744
745Likely BSP dependent.  A default implementation for memory mapped linear access
746is easy to provide.  The current heap implementation supports all properties
747demanded by bus_dma (including the boundary constraint).
748
749== RTEMS Replacements by File Description ==
750
751Note:  Files with a status of USB are used by the USB test and have at least
752been partially tested.  If they contain both USB and Nic, then they are used
753by both and MAY contain methods that have not been tested yet.  Files that
754are only used by the Nic test are the most suspect.
755
756----
757rtems-libbsd File:      rtems-bsd-assert.c
758FreeBSD File:           rtems-bsd-config.h redefines BSD_ASSERT.
759Description:            This file contains the support method rtems_bsd_assert_func().
760Status:                 USB, Nic
761
762rtems-libbsd File:      rtems-bsd-autoconf.c
763FreeBSD File:           FreeBSD has BSP specific autoconf.c
764Description:            This file contains configuration methods that are used to setup the system.
765Status:                 USB
766
767rtems-libbsd File:      rtems-bsd-bus-dma.c
768FreeBSD File:           FreeBSD has BSP specific busdma_machdep.c
769Description:           
770Status:                 USB, Nic
771
772rtems-libbsd File:      rtems-bsd-bus-dma-mbuf.c       
773FreeBSD File:           FreeBSD has BSP specific busdma_machdep.c
774Description:           
775Status:                 Nic
776
777rtems-libbsd File:      rtems-bsd-callout.c             
778FreeBSD File:           kern/kern_timeout.c
779Description:           
780Status:                 USB, Nic
781
782rtems-libbsd File:      rtems-bsd-cam.c
783FreeBSD File:           cam/cam_sim.c
784Description:           
785Status:                 USB
786
787rtems-libbsd File:      rtems-bsd-condvar.c             
788FreeBSD File:           kern/kern_condvar.c
789Description:           
790Status:                 USB
791
792rtems-libbsd File:      rtems-bsd-copyinout.c
793FreeBSD File:           bsp specific copyinout.c )
794Description:            Note: The FreeBSD file is split with some methods being in rtems-bsd-support
795Status:                 Nic
796
797rtems-libbsd File:      rtems-bsd-delay.c
798FreeBSD File:           bsp specific file with multiple names
799Description:           
800Status:                 USB, Nic
801
802rtems-libbsd File:      rtems-bsd-descrip.c
803FreeBSD File:           kern/kern_descrip.c
804Description:           
805Status:                 Nic
806
807rtems-libbsd File:      rtems-bsd-generic.c             
808FreeBSD File:           kern/sys_generic.c
809Description:           
810Status:                 Nic
811
812rtems-libbsd File:      rtems-bsd-init.c
813FreeBSD File:           N/A
814Description:           
815Status:                 USB, Nic
816
817rtems-libbsd File:      rtems-bsd-init-with-irq.c
818FreeBSD File:           N/A
819Description:           
820Status:                 USB, Nic
821
822rtems-libbsd File:      rtems-bsd-jail.c
823FreeBSD File:           kern/kern_jail.c
824Description:           
825Status:                 USB, Nic
826
827rtems-libbsd File:      rtems-bsd-lock.c
828FreeBSD File:           kern/subr_lock.c
829Description:           
830Status:                 USB, Nic
831
832rtems-libbsd File:      rtems-bsd-log.c         
833FreeBSD File:           kern/subr_prf.c
834Description:           
835Status:                 Nic
836
837rtems-libbsd File:      rtems-bsd-malloc.c
838FreeBSD File:           kern/kern_malloc.c
839Description:           
840Status:                 USB, Nic
841
842rtems-libbsd File:      rtems-bsd-mutex.c
843FreeBSD File:           kern/kern_mutex.c
844Description:           
845Status:                 USB, Nic
846
847rtems-libbsd File:      rtems-bsd-newproc.c
848FreeBSD File:           N/A
849Description:           
850Status:                 Nic
851
852rtems-libbsd File:      rtems-bsd-nexus.c
853FreeBSD File:           bsp specific nexus.c
854Description:           
855Status:                 USB
856
857rtems-libbsd File:      rtems-bsd-panic.c               
858FreeBSD File:           boot/common/panic.c
859Description:           
860Status:                 USB, Nic
861
862rtems-libbsd File:      rtems-bsd-rwlock.c             
863FreeBSD File:           kern_rwlock.c
864Description:           
865Status:                 USB, Nic
866
867rtems-libbsd File:      rtems-bsd-shell.c               
868FreeBSD File:           N/A
869Description:           
870Status:                 USB
871
872rtems-libbsd File:      rtems-bsd-signal.c             
873FreeBSD File:           kern/kern_sig.c
874Description:           
875Status:                 Nic
876
877rtems-libbsd File:      rtems-bsd-smp.c                 
878FreeBSD File:           N/A
879Description:           
880Status:                 Nic
881
882rtems-libbsd File:      rtems-bsd-support.c             
883FreeBSD File:           bsp specific copyinout.c
884Description:            Note: the FreeBSD file is split with some methods being in rtems-bsd-copyinout.
885Status:                 USB, Nic
886
887rtems-libbsd File:      rtems-bsd-sx.c                 
888FreeBSD File:           kern/kern_sx.c
889Description:            Status: USB, Nic
890
891rtems-libbsd File:      rtems-bsd-synch.c               
892FreeBSD File:           kern/kern_synch.c
893Description:           
894Status:                 USB, Nic
895
896rtems-libbsd File:      rtems-bsd-syscalls.c           
897FreeBSD File:           User API for kern/uipc_syscalls.c
898Description:           
899Status:                 Nic
900
901rtems-libbsd File:      rtems-bsd-sysctlbyname.c       
902FreeBSD File:           User API for sysctlbyname(3)
903Description:           
904Status:
905
906rtems-libbsd File:      rtems-bsd-sysctl.c             
907FreeBSD File:           User API for sysctl(8)
908Description:           
909Status:
910
911rtems-libbsd File:      rtems-bsd-sysctlnametomib.c     
912FreeBSD File:           User API for sysctlnametomib
913Description:           
914Status:
915
916rtems-libbsd File:      rtems-bsd-taskqueue.c           
917FreeBSD File:           kern/subr_taskqueue.c
918Description:           
919Status:                 Nic
920
921rtems-libbsd File:      rtems-bsd-thread.c                     
922FreeBSD File:           kern/kern_kthread.c
923Description:           
924Status:                 USB, Nic
925
926rtems-libbsd File:      rtems-bsd-timeout.c             
927FreeBSD File:           kern/kern_timeout.c
928Description:           
929Status:                 Nic
930
931rtems-libbsd File:      rtems-bsd-timesupport.c         
932FreeBSD File:           kern/kern_clock.c
933Description:           
934Status:                 Nic
935
936rtems-libbsd File:      rtems-bsd-vm_glue.c             
937FreeBSD File:           vm/vm_glue.c
938Description:           
939Status:                 USB, Nic
940----
941
942== Notes by File ==
943
944altq_subr.c - Arbitrary choices were made in this file that RTEMS would
945not support tsc frequency change.  Additionally, the clock frequency
946for machclk_freq is always measured for RTEMS.
947
948conf.h - In order to add make_dev and destroy_dev, variables in the cdev
949structure that were not being used were conditionally compiled out. The
950capability of supporting children did not appear to be needed and was
951not implemented in the rtems version of these routines.
952 
953== NICs Status ==
954
955----
956Driver                  Symbol                          Status
957======                  ======                          ======
958RealTek                 _bsd_re_pcimodule_sys_init      Links
959EtherExpress            _bsd_fxp_pcimodule_sys_init     Links
960DEC tulip               _bsd_dc_pcimodule_sys_init      Links
961Broadcom BCM57xxx       _bsd_bce_pcimodule_sys_init     Links
962Broadcom BCM4401        _bsd_bfe_pcimodule_sys_init     Links
963Broadcom BCM570x        _bsd_bge_pcimodule_sys_init     Needs Symbols (A)
964E1000 IGB               _bsd_igb_pcimodule_sys_init     Links
965E1000 EM                _bsd_em_pcimodule_sys_init      Links
966----
967
968
969Symbols (A)
970         pci_get_vpd_ident
971 
972== Problems to report to FreeBSD ==
973
974The MMAP_NOT_AVAILABLE define is inverted on its usage.  When it is
975defined the mmap method is called. Additionally, it is not used
976thoroughly. It is not used in the unmap portion of the source.
977The file rec_open.c uses the define MMAP_NOT_AVAILABLE to wrap
978the call to mmap and file rec_close.c uses the munmap method.
979
980
981
Note: See TracBrowser for help on using the repository browser.