source: rtems-libbsd/libbsd.txt @ b6d5758

4.1155-freebsd-126-freebsd-12freebsd-9.3
Last change on this file since b6d5758 was b6d5758, checked in by Sebastian Huber <sebastian.huber@…>, on 05/14/14 at 07:19:25

Add some installation hints

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