source: rtems-libbsd/libbsd.txt @ 9d955bc

4.1155-freebsd-126-freebsd-12freebsd-9.3
Last change on this file since 9d955bc was 9d955bc, checked in by Christian Mauderer <Christian.Mauderer@…>, on 05/14/14 at 09:57:56

doc: Fix link and header

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