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

5-freebsd-12
Last change on this file since 9ff995c was 9ff995c, checked in by Sebastian Huber <sebastian.huber@…>, on Sep 21, 2018 at 8:27:28 AM

libbsd.txt: Remove linker set paragraph

These linker sections are now mandatory for the RTEMS initialization.

  • Property mode set to 100644
File size: 43.6 KB
Line 
1RTEMS BSD Library Guide
2=======================
3:toc:
4:icons:
5:numbered:
6:website: http://www.rtems.org/
7
8The libbsd makes FreeBSD subsystems like TCP/IP, USB, SD and some more usable
9for RTEMS. It tries to follow the FreeBSD development as close as possible and
10therefore is updated to the latest FreeBSD HEAD revision from time to time.
11To find out which version of FreeBSD is currently used as the base version for
12libbsd please take a look at the
13https://git.rtems.org/rtems-libbsd/log/freebsd-org[freebsd-org] submodule.
14
15This is a guide which captures information on the
16process of merging code from FreeBSD, building this library,
17RTEMS specific support files, and general guidelines on what
18modifications to the FreeBSD source are permitted.
19
20Goals of this effort are
21
22* update TCP/IP and provide USB in RTEMS,
23* ease updating to future FreeBSD versions,
24* ease tracking changes in FreeBSD code,
25* minimize manual changes in FreeBSD code, and
26* define stable kernel/device driver API which is implemented
27by both RTEMS and FreeBSD. This is the foundation of the port.
28
29We will work to push our changes upstream to the FreeBSD Project
30and minimize changes required at each update point.
31
32*******************************************************************************
33This is a work in progress and is very likely to be incomplete.
34Please help by adding to it.
35*******************************************************************************
36
37== Getting Started
38
39=== Tool Chain ===
40
41You need a tool chain for RTEMS based on the latest RTEMS Source Builder (RSB).
42
43=== Installation Overview ===
44
45. You must configure your BSP with the +--disable-networking+ option to disable
46the old network stack.  Make sure no header files of the old network stack are
47installed.
48
49. Clone the Git repository +git clone git://git.rtems.org/rtems-libbsd.git+.
50. Change into the RTEMS BSD library root directory.
51. If you want to run tests with a custom IP configuration instead of the default
52  one you can use an adjusted `config.inc` configuration file.
53. Run +waf configure ...+.
54. Run +waf+.
55. Run +waf install+.
56
57Refer to the README.waf for Waf building instructions.
58
59Make sure the submodules have been initialised and are updated. If a 'git
60status' says `rtems_waf` need updating run the submodule update command:
61
62 $ git submodule sync
63 $ git submodule rtems_waf update
64
65=== Board Support Package Requirements ===
66
67You need the latest RTEMS version to build the libbsd master.  The Board
68Support Package (BSP) must support the
69http://www.rtems.org/onlinedocs/doxygen/cpukit/html/group\__rtems\__interrupt__extension.html[Interrupt Manager Extension]
70// The first underscores have to be masked to stop asciidoc interpreting them
71to make use of generic FreeBSD based drivers.
72
73=== Board Support Package Configuration and Build ===
74
75You need to configure RTEMS for the desired BSP and install it.  The BSP must
76be configured with a disabled network stack.  The BSD library containing the
77new network stack is a separate package.  Using a BSP installation containing
78the old network stack may lead to confusion and unpredictable results.
79
80The following script is used to build the `arm/xilinx_zynq_a9_qemu` BSP for
81our internal testing purposes:
82
83-------------------------------------------------------------------------------
84#!/bin/sh
85
86cd ${HOME}/sandbox
87rm -rf b-xilinx_zynq_a9_qemu
88mkdir b-xilinx_zynq_a9_qemu
89cd b-xilinx_zynq_a9_qemu
90${HOME}/git-rtems/configure \
91        --prefix=${HOME}/sandbox/install \
92        --target=arm-rtems5 \
93        --enable-rtemsbsp=xilinx_zynq_a9_qemu \
94        --disable-networking && \
95        make && \
96        make install
97-------------------------------------------------------------------------------
98
99The `arm/xilinx_zynq_a9_qemu` BSP running on the Qemu simulator has some
100benefits for development and test of the BSD library
101
102* it offers a NULL pointer read and write protection,
103* Qemu is a fast simulator,
104* Qemu provides support for GDB watchpoints,
105* Qemu provides support for virtual Ethernet networks, e.g. TUN and bridge
106devices (you can run multiple test instances on one virtual network).
107
108=== BSD Library Configuration and Build ===
109
110The build system based on the Waf build system. To build with Waf please refer
111to the README.waf file.
112
113Note that the libbsd supports different buildsets. These can be selected with
114the `--buildset=xxx.ini` option during the configure phase. Take a look at the
115comments in `buildset/*.ini` to see which build sets are officially supported.
116
117You can also create and provide your own buildset configuration. But remember
118that it's quite easy to break something by disabling the wrong modules. Only the
119configurations in the `buildset` directory are officially maintained.
120
121===== Example Configuration for Network Tests =====
122
123If you need some other IP configuration for the network tests that use a fixed
124IP config you can copy `config.inc` to a location outside to the source tree and
125adapt it. Then use the option `--net-test-config=NET_CONFIG` to pass the file to
126waf's configure command.
127
128-------------------------------------------------------------------------------
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
133-------------------------------------------------------------------------------
134
135=== BSD Library Initialization ===
136
137To initialise the BSD Library create a suitable rc.conf file. The FreeBSD man
138page rc.conf(5) provides the details needed to create a suitable format file:
139
140 https://www.freebsd.org/cgi/man.cgi?rc.conf
141
142You can call one of three functions to run the initialisation once BSD has
143initialised:
144
145 - rtems_bsd_run_etc_rc_conf: Run /etc/rc.conf.
146 - rtems_bsd_run_rc_conf: Run a user supplied file.
147 - rtems_bsd_run_rc_conf_script: Run the in memory line feed separated text string.
148
149For exapmle:
150
151 void
152 network_init(void)
153 {
154   rtems_status_code sc;
155
156   sc = rtems_bsd_initialize();
157   assert(sc == RTEMS_SUCCESSFUL);
158
159   rtems_bsd_run_etc_rc_conf(true); /* verbose = true */
160
161}
162
163By default the networking support is builtin. Other directives can be added and
164are found in 'machine/rtems-bsd-rc-conf-directives.h'. Please check the file
165for the list.
166
167The following network names are supported:
168
169  cloned_interfaces
170  ifconfig_'interface'
171  defaultrouter
172  hostname
173
174For example:
175
176 #
177 # My BSD initialisation.
178 #
179 hostname="myhost"
180 cloned_interfaces="vlan0 vlan1"
181 ifconfig_re0="inet inet 10.10.10.10 netmask 255.255.255.0"
182 fconfig_vlan0="inet 10.11.10.10 255.255.255.0 vlan 101 vlandev re0"
183 defaultrouter="10.10.10.1"
184
185You can also intialise the BSD library using code. The following code to
186initialize the BSD library:
187
188-------------------------------------------------------------------------------
189#include <assert.h>
190#include <sysexits.h>
191
192#include <machine/rtems-bsd-commands.h>
193#include <rtems/bsd/bsd.h>
194
195static void
196network_ifconfig_lo0(void)
197{
198        int exit_code;
199        char *lo0[] = {
200                "ifconfig",
201                "lo0",
202                "inet",
203                "127.0.0.1",
204                "netmask",
205                "255.255.255.0",
206                NULL
207        };
208        char *lo0_inet6[] = {
209                "ifconfig",
210                "lo0",
211                "inet6",
212                "::1",
213                "prefixlen",
214                "128",
215                NULL
216        };
217
218        exit_code = rtems_bsd_command_ifconfig(RTEMS_BSD_ARGC(lo0), lo0);
219        assert(exit_code == EX_OK);
220
221        exit_code = rtems_bsd_command_ifconfig(RTEMS_BSD_ARGC(lo0_inet6), lo0_inet6);
222        assert(exit_code == EX_OK);
223}
224
225void
226network_init(void)
227{
228        rtems_status_code sc;
229
230        sc = rtems_bsd_initialize();
231        assert(sc == RTEMS_SUCCESSFUL);
232
233        network_ifconfig_lo0();
234}
235-------------------------------------------------------------------------------
236
237This performs the basic network stack initialization with a loopback interface.
238Further initialization must be done using the standard BSD network
239configuration commands
240http://www.freebsd.org/cgi/man.cgi?query=ifconfig&sektion=8[IFCONFIG(8)]
241using `rtems_bsd_command_ifconfig()` and
242http://www.freebsd.org/cgi/man.cgi?query=route&sektion=8[ROUTE(8)]
243using `rtems_bsd_command_route()`.  For an example please have a look at
244`testsuite/include/rtems/bsd/test/default-network-init.h`.
245
246=== Task Priorities and Stack Size ===
247
248The default task priority is 96 for the interrupt server task (name "IRQS"), 98
249for the timer server task (name "TIME") and 100 for all other tasks.  The
250application may provide their own implementation of the
251`rtems_bsd_get_task_priority()` function (for example in the module which calls
252`rtems_bsd_initialize()`) if different values are desired.
253
254The task stack size is determined by the `rtems_bsd_get_task_stack_size()`
255function which may be provided by the application in case the default is not
256appropriate.
257
258=== Size for Allocator Domains ===
259
260The size for an allocator domain can be specified via the
261`rtems_bsd_get_allocator_domain_size()` function.  The application may provide
262their own implementation of the `rtems_bsd_get_allocator_domain_size()`
263function (for example in the module which calls `rtems_bsd_initialize()`) if
264different values are desired.  The default size is 8MiB for all domains.
265
266=== Redirecting or Disabling the Output ===
267
268A lot of system messages are printed to the stdout by default. If you want to
269redirect them you can overwrite the default print handler. That can even be done
270before the libbsd initialization to catch all messages. An example would look
271like follows:
272
273-------------------------------------------------------------------------------
274int my_vprintf_handler(int level, const char *fmt, va_list ap) {
275        /* Do something with the messages. */
276
277        return number_of_printed_chars;
278}
279
280...
281        /* In your initialization: */
282        rtems_bsd_vprintf_handler old;
283        old = rtems_bsd_set_vprintf_handler(my_vprintf_handler);
284...
285-------------------------------------------------------------------------------
286
287As a special case, you can set the `rtems_bsd_vprintf_handler_mute(...)`
288provided by libbsd to suppress all output.
289
290== Network Stack Features
291
292http://roy.marples.name/projects/dhcpcd/index[DHCPCD(8)]:: DHCP client
293
294https://developer.apple.com/library/mac/documentation/Networking/Reference/DNSServiceDiscovery_CRef/Reference/reference.html[dns_sd.h]:: DNS Service Discovery
295
296http://www.opensource.apple.com/source/mDNSResponder/mDNSResponder-320.10/mDNSCore/mDNSEmbeddedAPI.h[mDNS]:: Multi-Cast DNS
297
298http://www.freebsd.org/cgi/man.cgi?query=unix&sektion=4[UNIX(4)]:: UNIX-domain protocol family
299
300http://www.freebsd.org/cgi/man.cgi?query=inet&sektion=4[INET(4)]:: Internet protocol family
301
302http://www.freebsd.org/cgi/man.cgi?query=inet6&sektion=4[INET6(4)]:: Internet protocol version 6 family
303
304http://www.freebsd.org/cgi/man.cgi?query=tcp&sektion=4[TCP(4)]:: Internet Transmission Control Protocol
305
306http://www.freebsd.org/cgi/man.cgi?query=udp&sektion=4[UDP(4)]:: Internet User Datagram Protocol
307
308http://www.freebsd.org/cgi/man.cgi?query=route&sektion=4[ROUTE(4)]:: Kernel packet forwarding database
309
310http://www.freebsd.org/cgi/man.cgi?query=bpf&sektion=4[BPF(4)]:: Berkeley Packet Filter
311
312http://www.freebsd.org/cgi/man.cgi?query=socket&sektion=2[SOCKET(2)]:: Create an endpoint for communication
313
314http://www.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2[KQUEUE(2)]:: Kernel event notification mechanism
315
316http://www.freebsd.org/cgi/man.cgi?query=select&sektion=2[SELECT(2)]:: Synchronous I/O multiplexing
317
318http://www.freebsd.org/cgi/man.cgi?query=poll&sektion=2[POLL(2)]:: Synchronous I/O multiplexing
319
320http://www.freebsd.org/cgi/man.cgi?query=route&sektion=8[ROUTE(8)]:: Manually manipulate the routing tables
321
322http://www.freebsd.org/cgi/man.cgi?query=ifconfig&sektion=8[IFCONFIG(8)]:: Configure network interface parameters
323
324http://www.freebsd.org/cgi/man.cgi?query=netstat&sektion=1[NETSTAT(1)]:: Show network status
325
326http://www.freebsd.org/cgi/man.cgi?query=ping&sektion=8[PING(8)]:: Send ICMP ECHO_REQUEST packets to network hosts
327
328http://www.freebsd.org/cgi/man.cgi?query=ping6&sektion=8[PING6(8)]:: Send ICMPv6 ECHO_REQUEST packets to network hosts
329
330http://www.freebsd.org/cgi/man.cgi?query=sysctl&sektion=3[SYSCTL(3)]:: Get or set system information
331
332http://www.freebsd.org/cgi/man.cgi?query=resolver&sektion=3[RESOLVER(3)]:: Resolver routines
333
334http://www.freebsd.org/cgi/man.cgi?query=gethostbyname&sektion=3[GETHOSTBYNAME(3)]:: Get network host entry
335
336== Network Interface Drivers
337
338=== Link Up/Down Events
339
340You can notifiy the application space of link up/down events in your network
341interface driver via the if_link_state_change(LINK_STATE_UP/LINK_STATE_DOWN)
342function.  The DHCPCD(8) client is a consumer of these events for example.
343Make sure that the interface flag IFF_UP and the interface driver flag
344IFF_DRV_RUNNING is set in case the link is up, otherwise ether_output() will
345return the error status ENETDOWN.
346
347== Shell Commands
348
349=== HOSTNAME(1)
350
351In addition to the standard options the RTEMS version of the HOSTNAME(1)
352command supports the -m flag to set/get the multicast hostname of the
353mDNS resolver instance.  See also rtems_mdns_sethostname() and
354rtems_mdns_gethostname().
355
356== Qemu
357
358Use the following script to set up a virtual network with three tap devices
359connected via one bridge device.
360
361-------------------------------------------------------------------------------
362#!/bin/sh -x
363
364user=`whoami`
365interfaces=(1 2 3)
366
367tap=qtap
368bri=qbri
369
370case $1 in
371        up)
372                sudo -i brctl addbr $bri
373                for i in ${interfaces[@]} ; do
374                        sudo -i tunctl -t $tap$i -u $user ;
375                        sudo -i ifconfig $tap$i up ;
376                        sudo -i brctl addif $bri $tap$i ;
377                done
378                sudo -i ifconfig $bri up
379                ;;
380        down)
381                for i in ${interfaces[@]} ; do
382                        sudo -i ifconfig $tap$i down ;
383                        sudo -i tunctl -d $tap$i ;
384                done
385                sudo -i ifconfig $bri down
386                sudo -i brctl delbr $bri
387                ;;
388esac
389-------------------------------------------------------------------------------
390
391Connect your Qemu instance to one of the tap devices, e.g.
392
393-------------------------------------------------------------------------------
394qemu-system-i386 -m 512 -boot a -cpu pentium3 \
395        -drive file=$HOME/qemu/pc386_fda,index=0,if=floppy,format=raw \
396        -drive file=fat:$HOME/qemu/hd,format=raw \
397        -net nic,model=e1000,macaddr=0e:b0:ba:5e:ba:11 \
398        -net tap,ifname=qtap1,script=no,downscript=no \
399        -nodefaults -nographic -serial stdio
400-------------------------------------------------------------------------------
401
402-------------------------------------------------------------------------------
403qemu-system-arm \
404        -serial null \
405        -serial mon:stdio \
406        -nographic \
407        -M xilinx-zynq-a9 \
408        -net nic,model=cadence_gem,macaddr=0e:b0:ba:5e:ba:11 \
409        -net tap,ifname=qtap1,script=no,downscript=no \
410        -m 256M \
411        -kernel build/arm-rtems5-xilinx_zynq_a9_qemu/media01.exe
412-------------------------------------------------------------------------------
413
414Make sure that each Qemu instance uses its own MAC address to avoid an address
415conflict (or otherwise use it as a test).
416
417To connect the Qemu instances with your local network use the following
418(replace 'eth0' with the network interface of your host).
419
420-------------------------------------------------------------------------------
421ifconfig eth0 0.0.0.0
422brctl addif qbri eth0
423dhclient qbri
424-------------------------------------------------------------------------------
425
426=== VDE and QEMU
427
428On FreeBSD you can create VDE or the Virtual Distributed Ethernet to create a
429network environment that does not need to run qemu as root or needing to drop
430the tap's privileges to run qemu.
431
432VDE creates a software switch with a default of 32 ports which means a single
433kernel tap can support 32 qemu networking sessions.
434
435To use VDE you need to build qemu with VDE support. The RSB can detect a VDE
436plug and enable VDE support in qemu when building. On FreeBSD install the VDE
437support with:
438
439 # pkg install -u vde2
440
441Build qemu with the RSB.
442
443To network create a bridge and a tap. The network is 10.10.1.0/24. On FreeBSD
444add to your /etc/rc.conf:
445
446 cloned_interfaces="bridge0 tap0"
447 autobridge_interfaces="bridge0"
448 autobridge_bridge0="re0 tap0"
449 ifconfig_re0="up"
450 ifconfig_tap0="up"
451 ifconfig_bridge0="inet 10.1.1.2 netmask 255.255.255.0"
452 defaultrouter="10.10.1.1"
453
454Start the VDE switch as root:
455
456 # sysctl net.link.tap.user_open=1
457 # sysctl net.link.tap.up_on_open=1
458 # vde_switch -d -s /tmp/vde1 -M /tmp/mgmt1 -tap tap0 -m 660 --mgmtmode 660
459 # chmod 660 /dev/tap0
460
461You can connect to the VDE switch's management channel using:
462
463 $ vdeterm /tmp/mgmt1
464
465To run qemu:
466
467 $ qemu-system-arm \
468        -serial null \
469        -serial mon:stdio \
470        -nographic \
471        -M xilinx-zynq-a9 \
472        -net nic,model=cadence_gem,macaddr=0e:b0:ba:5e:ba:11 \
473        -net vde,id=vde0,sock=/tmp/vde1
474        -m 256M \
475        -kernel build/arm-rtems5-xilinx_zynq_a9_qemu/rcconf02.exe
476
477== Issues and TODO
478
479* PCI support on x86 uses a quick and dirty hack, see pci_reserve_map().
480
481* Priority queues are broken with clustered scheduling.
482
483* Per-CPU data should be enabled once the new stack is ready for SMP.
484
485* Per-CPU NETISR(9) should be enabled onece the new stack is ready for SMP.
486
487* Multiple routing tables are not supported.  Every FIB value is set to zero
488  (= BSD_DEFAULT_FIB).
489
490* Process identifiers are not supported.  Every PID value is set to zero
491  (= BSD_DEFAULT_PID).
492
493* User credentials are not supported.  The following functions allow the
494  operation for everyone
495  - prison_equal_ip4(),
496  - chgsbsize(),
497  - cr_cansee(),
498  - cr_canseesocket() and
499  - cr_canseeinpcb().
500
501* A basic USB functionality test that is known to work on Qemu is desirable.
502
503* Adapt generic IRQ PIC interface code to Simple Vectored Interrupt Model
504  so that those architectures can use new TCP/IP and USB code.
505
506* freebsd-userspace/rtems/include/sys/syslog.h is a copy from the old
507  RTEMS TCP/IP stack. For some reason, the __printflike markers do not
508  compile in this environment. We may want to use the FreeBSD syslog.h
509  and get this addressed.
510
511* in_cksum implementations for architectures not supported by FreeBSD.
512  This will require figuring out where to put implementations that do
513  not originate from FreeBSD and are populated via the script.
514
515* MAC support functions are not thread-safe ("freebsd/lib/libc/posix1e/mac.c").
516
517* IFCONFIG(8): IEEE80211 support is disabled.  This module depends on a XML
518  parser and mmap().
519
520* get_cyclecount(): The implementation is a security problem.
521
522* What to do with the priority parameter present in the FreeBSD synchronization
523  primitives and the thread creation functions?
524
525* TASKQUEUE(9): Support spin mutexes.
526
527* ZONE(9): Review allocator lock usage in rtems-bsd-chunk.c.
528
529* KQUEUE(2): Choose proper lock for global kqueue list.
530
531* TIMEOUT(9): Maybe use special task instead of timer server to call
532  callout_tick().
533
534* sysctl_handle_opaque(): Implement reliable snapshots.
535
536* PING6(8): What to do with SIGALARM?
537
538* <sys/param.h>: Update Newlib to use a MSIZE of 256.
539
540* BPF(4): Add support for zero-copy buffers.
541
542* UNIX(4): Fix race conditions in the area of socket object and file node
543  destruction.  Add support for file descriptor transmission via control
544  messages.
545
546* PRINTF(9): Add support for log(), the %D format specifier is missing in the
547  normal printf() family.
548
549* Why is the interrupt server used?  The BSD interrupt handlers can block on
550synchronization primitives like mutexes.  This is in contrast to RTEMS
551interrupt service routines.  The BSPs using the generic interrupt support must
552implement the `bsp_interrupt_vector_enable()` and
553`bsp_interrupt_vector_disable()` routines.  They normally enable/disable a
554particular interrupt source at the interrupt controller.  This can be used to
555implement the interrupt server.  The interrupt server is a task that wakes-up
556in case an associated interrupt happens.  The interrupt source is disabled in
557a generic interrupt handler that wakes-up the interrupt server task.   Once the
558postponed interrupt processing is performed in the interrupt server the
559interrupt source is enabled again.
560
561* Convert all BSP linkcmds to use a linkcmds.base so the sections are
562easier to insert.
563
564* NIC Device Drivers
565- Only common PCI NIC drivers have been included in the initial set. These
566do not include any system on chip or ISA drivers.
567- PCI configuration probe does not appear to happen to determine if a
568NIC is in I/O or memory space. We have worked around this by using a
569static hint to tell the fxp driver the correct mode. But this needs to
570be addressed.
571- The ISA drivers require more BSD infrastructure to be addressed. This was
572outside the scope of the initial porting effort.
573
574== FreeBSD Source
575
576You should be able to rely on FreebSD manual pages and documentation
577for details on the code itself.
578
579== BSD Library Source
580
581== Initialization of the BSD Library
582
583The initialization of the BSD library is based on the FreeBSD SYSINIT(9)
584infrastructure.  The key to initializing a system is to ensure that the desired
585device drivers are explicitly pulled into the linked application.  This plus
586linking against the BSD library (`libbsd.a`) will pull in the necessary FreeBSD
587infrastructure.
588
589The FreeBSD kernel is not a library like the RTEMS kernel.  It is a bunch of
590object files linked together.  If we have a library, then creating the
591executable is simple.  We begin with a start symbol and recursively resolve all
592references.  With a bunch of object files linked together we need a different
593mechanism.  Most object files don't know each other.  Lets say we have a driver
594module.  The rest of the system has no references to this driver module.  The
595driver module needs a way to tell the rest of the system: Hey, kernel I am
596here, please use my services!
597
598This registration of independent components is performed by SYSINIT(9) and
599specializations:
600
601http://www.freebsd.org/cgi/man.cgi?query=SYSINIT
602
603The SYSINIT(9) uses some global data structures that are placed in a certain
604section.  In the linker command file we need this:
605
606-------------------------------------------------------------------------------
607.rtemsroset : {
608        KEEP (*(SORT(.rtemsroset.*)))
609}
610
611.rtemsrwset : {
612        KEEP (*(SORT(.rtemsrwset.*)))
613}
614-------------------------------------------------------------------------------
615
616This results for example in this executable layout:
617
618-------------------------------------------------------------------------------
619[...]
620 *(SORT(.rtemsroset.*))
621 .rtemsroset.bsd.modmetadata_set.begin
622                0x000000000025fe00        0x0 libbsd.a(rtems-bsd-init.o)
623                0x000000000025fe00                _bsd__start_set_modmetadata_set
624 .rtemsroset.bsd.modmetadata_set.content
625                0x000000000025fe00        0x8 libbsd.a(rtems-bsd-nexus.o)
626 .rtemsroset.bsd.modmetadata_set.content
627                0x000000000025fe08        0x4 libbsd.a(kern_module.o)
628[...]
629 .rtemsroset.bsd.modmetadata_set.content
630                0x000000000025fe68        0x4 libbsd.a(mii.o)
631 .rtemsroset.bsd.modmetadata_set.content
632                0x000000000025fe6c        0x4 libbsd.a(mii_bitbang.o)
633 .rtemsroset.bsd.modmetadata_set.end
634                0x000000000025fe70        0x0 libbsd.a(rtems-bsd-init.o)
635                0x000000000025fe70                _bsd__stop_set_modmetadata_set
636[...]
637.rtemsrwset     0x000000000030bad0      0x290
638 *(SORT(.rtemsrwset.*))
639 .rtemsrwset.bsd.sysinit_set.begin
640                0x000000000030bad0        0x0 libbsd.a(rtems-bsd-init.o)
641                0x000000000030bad0                _bsd__start_set_sysinit_set
642 .rtemsrwset.bsd.sysinit_set.content
643                0x000000000030bad0        0x4 libbsd.a(rtems-bsd-nexus.o)
644 .rtemsrwset.bsd.sysinit_set.content
645                0x000000000030bad4        0x8 libbsd.a(rtems-bsd-thread.o)
646 .rtemsrwset.bsd.sysinit_set.content
647                0x000000000030badc        0x4 libbsd.a(init_main.o)
648[...]
649 .rtemsrwset.bsd.sysinit_set.content
650                0x000000000030bd54        0x4 libbsd.a(frag6.o)
651 .rtemsrwset.bsd.sysinit_set.content
652                0x000000000030bd58        0x8 libbsd.a(uipc_accf.o)
653 .rtemsrwset.bsd.sysinit_set.end
654                0x000000000030bd60        0x0 libbsd.a(rtems-bsd-init.o)
655                0x000000000030bd60                _bsd__stop_set_sysinit_set
656[...]
657-------------------------------------------------------------------------------
658
659Here you can see, that some global data structures are collected into
660continuous memory areas.  This memory area can be identified by start and stop
661symbols.  This constructs a table of uniform items.
662
663The low level FreeBSD code calls at some time during the initialization the
664mi_startup() function (machine independent startup).  This function will sort
665the SYSINIT(9) set and call handler functions which perform further
666initialization.  The last step is the scheduler invocation.
667
668The SYSINIT(9) routines are run in mi_startup() which is called by
669rtems_bsd_initialize().
670
671This is also explained in "The Design and Implementation of the FreeBSD
672Operating System" section 14.3 "Kernel Initialization".
673
674In RTEMS we have a library and not a bunch of object files.  Thus we need a way
675to pull-in the desired services out of the libbsd.  Here the
676`rtems-bsd-sysinit.h` comes into play.  The SYSINIT(9) macros have been
677modified and extended for RTEMS in `<sys/kernel.h>`:
678
679-------------------------------------------------------------------------------
680#ifndef __rtems__
681#define C_SYSINIT(uniquifier, subsystem, order, func, ident)    \
682        static struct sysinit uniquifier ## _sys_init = {       \
683                subsystem,                                      \
684                order,                                          \
685                func,                                           \
686                (ident)                                         \
687        };                                                      \
688        DATA_SET(sysinit_set,uniquifier ## _sys_init)
689#else /* __rtems__ */
690#define SYSINIT_ENTRY_NAME(uniquifier)                          \
691        _bsd_ ## uniquifier ## _sys_init
692#define SYSINIT_REFERENCE_NAME(uniquifier)                      \
693        _bsd_ ## uniquifier ## _sys_init_ref
694#define C_SYSINIT(uniquifier, subsystem, order, func, ident)    \
695        struct sysinit SYSINIT_ENTRY_NAME(uniquifier) = {       \
696                subsystem,                                      \
697                order,                                          \
698                func,                                           \
699                (ident)                                         \
700        };                                                      \
701        RWDATA_SET(sysinit_set,SYSINIT_ENTRY_NAME(uniquifier))
702#define SYSINIT_REFERENCE(uniquifier)                           \
703        extern struct sysinit SYSINIT_ENTRY_NAME(uniquifier);   \
704        static struct sysinit const * const                     \
705        SYSINIT_REFERENCE_NAME(uniquifier) __used               \
706        = &SYSINIT_ENTRY_NAME(uniquifier)
707#define SYSINIT_MODULE_REFERENCE(mod)                           \
708        SYSINIT_REFERENCE(mod ## module)
709#define SYSINIT_DRIVER_REFERENCE(driver, bus)                   \
710        SYSINIT_MODULE_REFERENCE(driver ## _ ## bus)
711#define SYSINIT_DOMAIN_REFERENCE(dom)                           \
712        SYSINIT_REFERENCE(domain_add_ ## dom)
713#endif /* __rtems__ */
714-------------------------------------------------------------------------------
715
716Here you see that the SYSINIT(9) entries are no longer static.  The
717\*_REFERENCE() macros will create references to the corresponding modules which
718are later resolved by the linker.  The application has to provide an object
719file with references to all required FreeBSD modules.
720
721The FreeBSD device model is quite elaborated (with follow-ups):
722
723http://www.freebsd.org/cgi/man.cgi?query=driver
724
725The devices form a tree with the Nexus device at a high-level.  This Nexus
726device is architecture specific in FreeBSD.  In RTEMS we have our own Nexus
727device, see `rtemsbsd/bsp/bsp-bsd-nexus-devices.c`.
728
729=== SYSCTL_NODE Example
730
731During development, we had an undefined reference to
732_bsd_sysctl__net_children that we had trouble tracking down. Thanks to
733Chris Johns, we located it. He explained how to read SYSCTL_NODE
734definitions. This line from freebsd/netinet/in_proto.c is attempting
735to add the "inet" node to the parent node "_net".
736
737----
738SYSCTL_NODE(_net,      PF_INET,         inet,   CTLFLAG_RW, 0,
739        "Internet Family");
740----
741
742Our problem was that we could not find where _bsd_sysctl__net_children
743was defined. Chris suggested that when in doubt compile with -save-temps
744and look at the preprocessed .i files. But he did not need that. He
745explained that this the symbol name _bsd_sysctl__net_children was
746automatically generated by a SYSCTL_NODE as follows:
747
748* _bsd_ - added by RTEMS modifications to SYSCTL_NODE macro
749* sysctl_ - boilerplace added by SYSCTL_NODE macro
750* "" - empty string for parent node
751* net - name of SYSCTL_NODE
752* children - added by SYSCTL macros
753
754This was all generated by a support macro declaring the node as this:
755
756----
757struct sysctl_oid_list SYSCTL_NODE_CHILDREN(parent, name);
758----
759
760Given this information, we located this SYSCTL_NODE declaration in
761kern/kern_mib.c
762
763----
764SYSCTL_NODE(, CTL_KERN,   kern,   CTLFLAG_RW, 0,
765        "High kernel, proc, limits &c");
766----
767
768== Core FreeBSD APIs and RTEMS Replacements ==
769
770=== SX(9) (Shared/exclusive locks) ===
771
772http://www.freebsd.org/cgi/man.cgi?query=sx
773
774Binary semaphores (this neglects the ability to allow shared access).
775
776=== MUTEX(9) (Mutual exclusion) ===
777
778http://www.freebsd.org/cgi/man.cgi?query=mutex
779
780Binary semaphores (not recursive mutexes are not supported this way).
781
782=== RWLOCK(9) (Reader/writer lock) ===
783
784http://www.freebsd.org/cgi/man.cgi?query=rwlock
785
786POSIX r/w lock.
787
788=== RMLOCK(9) (Reader/writer lock optimized for mostly read access patterns) ===
789
790Note:  This object was implemented as a wrapper for RWLOCK in the rm_lock header file.
791
792http://www.freebsd.org/cgi/man.cgi?query=rmlock
793
794POSIX r/w lock.
795
796=== CONDVAR(9) (Condition variables) ===
797
798http://www.freebsd.org/cgi/man.cgi?query=condvar
799
800POSIX condition variables with modifications (hack).
801
802=== CALLOUT(9) (Timer functions) ===
803
804http://www.freebsd.org/cgi/man.cgi?query=callout
805
806Timer server.
807
808=== TASKQUEUE(9) (Asynchronous task execution) ===
809
810http://www.freebsd.org/cgi/man.cgi?query=taskqueue
811
812TBD.
813
814=== KTHREAD(9), KPROC(9) (Tasks) ===
815
816http://www.freebsd.org/cgi/man.cgi?query=kthread
817
818http://www.freebsd.org/cgi/man.cgi?query=kproc
819
820Tasks.
821
822=== ZONE(9) (Zone allocator) ===
823
824http://www.freebsd.org/cgi/man.cgi?query=zone
825
826TBD.
827
828=== devfs (Device file system) ===
829
830There is a minimal implementation based on IMFS. The mount point is fixed to
831"/dev". Note that the devfs is only used by the cdev subsystem. cdev has been
832adapted so that the full path (including the leading "/dev") is given to devfs.
833This saves some copy operations.
834
835devfs_create() first creates the full path and then creates an IMFS generic node
836for the device.
837
838TBD: remove empty paths on devfs_destroy().
839
840=== psignal (Signals) ===
841
842TBD.  Seems to be not needed.
843
844=== poll, select ===
845
846TBD.  Seems to be not needed.
847
848=== RMAN(9) (Resource management) ===
849
850http://www.freebsd.org/cgi/man.cgi?query=rman
851
852TBD.  Seems to be not needed.
853
854=== DEVCLASS(9), DEVICE(9), DRIVER(9), MAKE_DEV(9) (Device management) ===
855
856http://www.freebsd.org/cgi/man.cgi?query=devclass
857
858http://www.freebsd.org/cgi/man.cgi?query=device
859
860http://www.freebsd.org/cgi/man.cgi?query=driver
861
862http://www.freebsd.org/cgi/man.cgi?query=make_dev
863
864Use FreeBSD implementation as far as possible.  FreeBSD has a nice API for
865dynamic device handling.  It may be interesting for RTEMS to use this API
866internally in the future.
867
868=== BUS_SPACE(9), BUS_DMA(9) (Bus and DMA access) ===
869
870http://www.freebsd.org/cgi/man.cgi?query=bus_space
871
872http://www.freebsd.org/cgi/man.cgi?query=bus_dma
873
874Likely BSP dependent.  A default implementation for memory mapped linear access
875is easy to provide.  The current heap implementation supports all properties
876demanded by bus_dma (including the boundary constraint).
877
878== RTEMS Replacements by File Description ==
879
880Note:  Files with a status of USB are used by the USB test and have at least
881been partially tested.  If they contain both USB and Nic, then they are used
882by both and MAY contain methods that have not been tested yet.  Files that
883are only used by the Nic test are the most suspect.
884
885----
886rtems-libbsd File:      rtems-bsd-assert.c
887FreeBSD File:           rtems-bsd-config.h redefines BSD_ASSERT.
888Description:            This file contains the support method rtems_bsd_assert_func().
889Status:                 USB, Nic
890
891rtems-libbsd File:      rtems-bsd-autoconf.c
892FreeBSD File:           FreeBSD has BSP specific autoconf.c
893Description:            This file contains configuration methods that are used to setup the system.
894Status:                 USB
895
896rtems-libbsd File:      rtems-bsd-bus-dma.c
897FreeBSD File:           FreeBSD has BSP specific busdma_machdep.c
898Description:
899Status:                 USB, Nic
900
901rtems-libbsd File:      rtems-bsd-bus-dma-mbuf.c
902FreeBSD File:           FreeBSD has BSP specific busdma_machdep.c
903Description:
904Status:                 Nic
905
906rtems-libbsd File:      rtems-bsd-callout.c
907FreeBSD File:           kern/kern_timeout.c
908Description:
909Status:                 USB, Nic
910
911rtems-libbsd File:      rtems-bsd-cam.c
912FreeBSD File:           cam/cam_sim.c
913Description:
914Status:                 USB
915
916rtems-libbsd File:      rtems-bsd-condvar.c
917FreeBSD File:           kern/kern_condvar.c
918Description:
919Status:                 USB
920
921rtems-libbsd File:      rtems-bsd-copyinout.c
922FreeBSD File:           bsp specific copyinout.c )
923Description:            Note: The FreeBSD file is split with some methods being in rtems-bsd-support
924Status:                 Nic
925
926rtems-libbsd File:      rtems-bsd-delay.c
927FreeBSD File:           bsp specific file with multiple names
928Description:
929Status:                 USB, Nic
930
931rtems-libbsd File:      rtems-bsd-descrip.c
932FreeBSD File:           kern/kern_descrip.c
933Description:
934Status:                 Nic
935
936rtems-libbsd File:      rtems-bsd-generic.c
937FreeBSD File:           kern/sys_generic.c
938Description:
939Status:                 Nic
940
941rtems-libbsd File:      rtems-bsd-init.c
942FreeBSD File:           N/A
943Description:
944Status:                 USB, Nic
945
946rtems-libbsd File:      rtems-bsd-init-with-irq.c
947FreeBSD File:           N/A
948Description:
949Status:                 USB, Nic
950
951rtems-libbsd File:      rtems-bsd-jail.c
952FreeBSD File:           kern/kern_jail.c
953Description:
954Status:                 USB, Nic
955
956rtems-libbsd File:      rtems-bsd-lock.c
957FreeBSD File:           kern/subr_lock.c
958Description:
959Status:                 USB, Nic
960
961rtems-libbsd File:      rtems-bsd-log.c
962FreeBSD File:           kern/subr_prf.c
963Description:
964Status:                 Nic
965
966rtems-libbsd File:      rtems-bsd-malloc.c
967FreeBSD File:           kern/kern_malloc.c
968Description:
969Status:                 USB, Nic
970
971rtems-libbsd File:      rtems-bsd-mutex.c
972FreeBSD File:           kern/kern_mutex.c
973Description:
974Status:                 USB, Nic
975
976rtems-libbsd File:      rtems-bsd-newproc.c
977FreeBSD File:           N/A
978Description:
979Status:                 Nic
980
981rtems-libbsd File:      rtems-bsd-nexus.c
982FreeBSD File:           bsp specific nexus.c
983Description:
984Status:                 USB
985
986rtems-libbsd File:      rtems-bsd-panic.c
987FreeBSD File:           boot/common/panic.c
988Description:
989Status:                 USB, Nic
990
991rtems-libbsd File:      rtems-bsd-rwlock.c
992FreeBSD File:           kern_rwlock.c
993Description:
994Status:                 USB, Nic
995
996rtems-libbsd File:      rtems-bsd-shell.c
997FreeBSD File:           N/A
998Description:
999Status:                 USB
1000
1001rtems-libbsd File:      rtems-bsd-signal.c
1002FreeBSD File:           kern/kern_sig.c
1003Description:
1004Status:                 Nic
1005
1006rtems-libbsd File:      rtems-bsd-smp.c
1007FreeBSD File:           N/A
1008Description:
1009Status:                 Nic
1010
1011rtems-libbsd File:      rtems-bsd-support.c
1012FreeBSD File:           bsp specific copyinout.c
1013Description:            Note: the FreeBSD file is split with some methods being in rtems-bsd-copyinout.
1014Status:                 USB, Nic
1015
1016rtems-libbsd File:      rtems-bsd-sx.c
1017FreeBSD File:           kern/kern_sx.c
1018Description:            Status: USB, Nic
1019
1020rtems-libbsd File:      rtems-bsd-synch.c
1021FreeBSD File:           kern/kern_synch.c
1022Description:
1023Status:                 USB, Nic
1024
1025rtems-libbsd File:      rtems-bsd-syscalls.c
1026FreeBSD File:           User API for kern/uipc_syscalls.c
1027Description:
1028Status:                 Nic
1029
1030rtems-libbsd File:      rtems-bsd-sysctlbyname.c
1031FreeBSD File:           User API for sysctlbyname(3)
1032Description:
1033Status:
1034
1035rtems-libbsd File:      rtems-bsd-sysctl.c
1036FreeBSD File:           User API for sysctl(8)
1037Description:
1038Status:
1039
1040rtems-libbsd File:      rtems-bsd-sysctlnametomib.c
1041FreeBSD File:           User API for sysctlnametomib
1042Description:
1043Status:
1044
1045rtems-libbsd File:      rtems-bsd-taskqueue.c
1046FreeBSD File:           kern/subr_taskqueue.c
1047Description:
1048Status:                 Nic
1049
1050rtems-libbsd File:      rtems-bsd-thread.c
1051FreeBSD File:           kern/kern_kthread.c
1052Description:
1053Status:                 USB, Nic
1054
1055rtems-libbsd File:      rtems-bsd-timeout.c
1056FreeBSD File:           kern/kern_timeout.c
1057Description:
1058Status:                 Nic
1059
1060rtems-libbsd File:      rtems-bsd-timesupport.c
1061FreeBSD File:           kern/kern_clock.c
1062Description:
1063Status:                 Nic
1064
1065rtems-libbsd File:      rtems-bsd-vm_glue.c
1066FreeBSD File:           vm/vm_glue.c
1067Description:
1068Status:                 USB, Nic
1069----
1070
1071== Notes by File ==
1072
1073altq_subr.c - Arbitrary choices were made in this file that RTEMS would
1074not support tsc frequency change.  Additionally, the clock frequency
1075for machclk_freq is always measured for RTEMS.
1076
1077conf.h - In order to add make_dev and destroy_dev, variables in the cdev
1078structure that were not being used were conditionally compiled out. The
1079capability of supporting children did not appear to be needed and was
1080not implemented in the rtems version of these routines.
1081
1082== NICs Status ==
1083
1084----
1085Driver                  Symbol                          Status
1086======                  ======                          ======
1087RealTek                 _bsd_re_pcimodule_sys_init      Links
1088EtherExpress            _bsd_fxp_pcimodule_sys_init     Links
1089DEC tulip               _bsd_dc_pcimodule_sys_init      Links
1090Broadcom BCM57xxx       _bsd_bce_pcimodule_sys_init     Links
1091Broadcom BCM4401        _bsd_bfe_pcimodule_sys_init     Links
1092Broadcom BCM570x        _bsd_bge_pcimodule_sys_init     Needs Symbols (A)
1093E1000 IGB               _bsd_igb_pcimodule_sys_init     Links
1094E1000 EM                _bsd_em_pcimodule_sys_init      Links
1095Cadence                 ?                               Links, works.
1096----
1097
1098To add a NIC edit rtemsbsd/include/bsp/nexus-devices.h and add the driver
1099reference to the architecture and/or BSP. For example to add the RealTek driver
1100add:
1101
1102SYSINIT_DRIVER_REFERENCE(re, pci);
1103
1104and to add the MII PHY driver add:
1105
1106SYSINIT_DRIVER_REFERENCE(rge, miibus);
1107
1108The PC BSP has these entries.
1109
1110Symbols (A)
1111         pci_get_vpd_ident
1112
1113=== Cadence ===
1114
1115The cadence driver works on the Xilinx Zynq platform. The hardware checksum
1116support works on real hardware but does not seem to be supported on qemu
1117therefore the default state is to disable TXCSUM and RXCSUM and this can be
1118enabled from the shell with:
1119
1120  # ifconfig cgem0 rxcsum txcsum
1121
1122or with an ioctl call to the network interface driver with SIOCSIFCAP and the
1123mask IFCAP_TXCSUM and IFCAP_RXCSUM set.
1124
1125== PF (Firewall) ==
1126
1127It is possible to use PF as a firewall. See
1128[https://www.freebsd.org/doc/handbook/firewalls-pf.html] for details on the
1129range of functions and for how to configure the firewall.
1130
1131The following is necessary to use PF on RTEMS:
1132
1133- You have to provide a +/etc/pf.os+ file. The firewall can use it for passive
1134  OS fingerprinting. If you don't want to use this feature, the file may contain
1135  nothing except a line of comment (for example "# empty").
1136
1137- If some filters use protocol names (like tcp or udp) you have to provide a
1138  +/etc/protocols+ file.
1139
1140- If some filters use service names (like ssh or http) you have to provide a
1141  +/etc/services+ file.
1142
1143- Create a rule file (normally +/etc/pf.conf+). See the FreeBSD manual for the
1144  syntax.
1145
1146- Load the rule file using the pfctl command and enable pf. Please note that the
1147  pfctl command needs a lot of stack. You should use at least
1148  RTEMS_MINIMUM_STACK_SIZE + 8192 Bytes of stack. An example initialisation can
1149  look like follows:
1150
1151----
1152        int exit_code;
1153        char *params[] = {
1154                "pfctl",
1155                "-f",
1156                "/etc/pf.conf",
1157                "-e",
1158                NULL
1159        };
1160
1161        exit_code = rtems_bsd_command_pfctl(ARGC(params), params);
1162        assert(exit_code == EXIT_SUCCSESS);
1163----
1164
1165=== Known restrictions ===
1166
1167- Currently PF on RTEMS always uses the configuration for memory restricted
1168  systems (on FreeBSD that means systems with less than 100 MB RAM). This is
1169  fixed in +pfctl_init_options()+.
1170
1171== Wireless Network (WLAN) ==
1172
1173The libbsd provides a basic support for WLAN. Note that currently this support
1174is still in an early state. The WLAN support is _not_ enabled in the default
1175buildset. You have to configure libbsd with the
1176`--buildset=buildset/everything.ini` to enable that feature.
1177
1178The following gives a rough overview over the necessary steps to connect to an
1179encrypted network with an RTL8188EU based WiFi dongle:
1180
1181- Reference all necessary module for your BSP. For some BSPs this is already
1182  done in the nexus-devices.h:
1183
1184----
1185        SYSINIT_MODULE_REFERENCE(wlan_ratectl_none);
1186        SYSINIT_MODULE_REFERENCE(wlan_sta);
1187        SYSINIT_MODULE_REFERENCE(wlan_amrr);
1188        SYSINIT_MODULE_REFERENCE(wlan_wep);
1189        SYSINIT_MODULE_REFERENCE(wlan_tkip);
1190        SYSINIT_MODULE_REFERENCE(wlan_ccmp);
1191        SYSINIT_DRIVER_REFERENCE(rtwn_usb, uhub);
1192        SYSINIT_REFERENCE(rtwn_rtl8188eufw);
1193----
1194
1195- Create your wlan device using ifconfig:
1196  +ifconfig wlan0 create wlandev rtwn0 up+
1197
1198- Start a wpa_supplicant instance for that device:
1199  + wpa_supplicant_fork -Dbsd -iwlan0 -c/media/mmcsd-0-0/wpa_supplicant.conf+
1200
1201Note that the wpa_supplicant will only be active till the device goes down. A
1202workaround is to just restart it every time it exits.
1203
1204=== Known restrictions ===
1205
1206- The network interface (e.g. wlan0) is currently not automatically created. It
1207  would be nice, if some service would create it as soon as for example a USB
1208  device is connected. In FreeBSD the names are assigned via rc.conf with lines
1209  like +wlans_rtwn0="wlan0"+.
1210
1211- wpa_supplicant hast to be started after the device is created. It has to be
1212  restarted every time the connection goes down. Instead of this behaviour,
1213  there should be some service that starts and restarts wpa_supplicant
1214  automatically if a interface is ready. Probably the dhcpcd hooks could be used
1215  for that.
1216
1217- The current wpa_supplicant implementation is protected with a lock so it can't
1218  be started more than one time. If multiple interface should be used, all have
1219  to be handled by that single instance. That makes it hard to add interfaces
1220  dynamically. wpa_supplicant should be reviewed thoroughly whether multiple
1221  instances could be started in parallel.
1222
1223- The control interface of wpa_supplicant most likely doesn't work. The wpa_cli
1224  application is not ported.
1225
1226== IPSec ==
1227
1228The IPSec support is optional in libbsd. It is disabled in the default build
1229set. Please make sure to use a build set with +netipsec = on+.
1230
1231To use IPSec the following configuration is necessary:
1232
1233----
1234SYSINIT_MODULE_REFERENCE(if_gif);
1235SYSINIT_MODULE_REFERENCE(cryptodev);
1236RTEMS_BSD_RC_CONF_SYSINT(rc_conf_ipsec)
1237RTEMS_BSD_DEFINE_NEXUS_DEVICE(cryptosoft, 0, 0, NULL);
1238----
1239
1240Alternatively you can use the `RTEMS_BSD_CONFIG_IPSEC` which also includes the
1241rc.conf support for ipsec. It's still necessary to include a crypto device in
1242your config (`cryptosoft` in the above sample).
1243
1244The necessary initialization steps for a IPSec connection are similar to the
1245steps on a FreeBSD-System. The example assumes the following setup:
1246
1247- RTEMS external IP: 192.168.10.1/24
1248- RTEMS internal IP: 10.10.1.1/24
1249- remote external IP: 192.168.10.10/24
1250- remote internal IP: 172.24.0.1/24
1251- shared key: "mysecretkey"
1252
1253With this the following steps are necessary:
1254
1255- Create a gif0 device:
1256
1257----
1258SHLL [/] #  ifconfig gif0 create
1259----
1260
1261- Configure the gif0 device:
1262
1263----
1264SHLL [/] # ifconfig gif0 10.10.1.1 172.24.0.1
1265SHLL [/] # ifconfig gif0 tunnel 192.168.10.1 192.168.10.10
1266----
1267
1268- Add a route to the remote net via the remote IP:
1269
1270----
1271SHLL [/] # route add 172.24.0.0/24 172.24.0.1
1272----
1273
1274- Call `setkey` with a correct rule set:
1275
1276----
1277SHLL [/] # cat /etc/setkey.conf
1278flush;
1279spdflush;
1280spdadd  10.10.1.0/24 172.24.0.0/24 any -P out ipsec esp/tunnel/192.168.10.1-192.168.10.10/use;
1281spdadd 172.24.0.0/24  10.10.1.0/24 any -P in  ipsec esp/tunnel/192.168.10.10-192.168.10.1/use;
1282SHLL [/] # setkey -f /etc/setkey.conf
1283----
1284
1285- Start a ike-daemon (racoon) with a correct configuration.
1286----
1287SHLL [/] # cat /etc/racoon.conf
1288path    pre_shared_key "/etc/racoon_psk.txt";
1289log     info;
1290
1291padding # options are not to be changed
1292{
1293        maximum_length                  20;
1294        randomize                       off;
1295        strict_check                    off;
1296        exclusive_tail                  off;
1297}
1298
1299listen  # address [port] that racoon will listen on
1300{
1301        isakmp                          192.168.10.1[500];
1302}
1303
1304remote 192.168.10.10 [500]
1305{
1306        exchange_mode                   main;
1307        my_identifier                   address 192.168.10.1;
1308        peers_identifier                address 192.168.10.10;
1309        proposal_check                  obey;
1310       
1311        proposal {
1312                encryption_algorithm    3des;
1313                hash_algorithm          md5;
1314                authentication_method   pre_shared_key;
1315                lifetime                time 3600 sec;
1316                dh_group                2;
1317        }
1318}
1319
1320sainfo (address 10.10.1.0/24 any address 172.24.0.0/24 any)
1321{
1322        pfs_group                       2;
1323        lifetime                        time 28800 sec;
1324        encryption_algorithm            3des;
1325        authentication_algorithm        hmac_md5;
1326        compression_algorithm           deflate;
1327}
1328SHLL [/] # cat /etc/racoon_psk.txt
1329192.168.10.10   mysecretkey
1330SHLL [/] # racoon -F -f /etc/racoon.conf
1331----
1332
1333All commands can be called via the respective API functions. For racoon there is
1334a `rtems_bsd_racoon_daemon()` function that forks of racoon as a task.
1335
1336Alternatively IPSec can also be configured via rc.conf entries:
1337
1338----
1339cloned_interfaces="gif0"
1340ifconfig_gif0="10.10.1.1 172.24.0.1 tunnel 192.168.10.1 192.168.10.10"
1341ike_enable="YES"
1342ike_program="racoon"
1343ike_flags="-F -f /etc/racoon.conf"
1344ike_priority="250"
1345
1346ipsec_enable="YES"
1347ipsec_file="/etc/setkey.conf"
1348----
1349
1350ATTENTION: It is possible that the first packets slip through the tunnel without
1351encryption (true for FreeBSD as well as RTEMS). You might want to set up a
1352firewall rule to prevent that.
1353
1354== Problems to report to FreeBSD ==
1355
1356The MMAP_NOT_AVAILABLE define is inverted on its usage.  When it is
1357defined the mmap method is called. Additionally, it is not used
1358thoroughly. It is not used in the unmap portion of the source.
1359The file rec_open.c uses the define MMAP_NOT_AVAILABLE to wrap
1360the call to mmap and file rec_close.c uses the munmap method.
Note: See TracBrowser for help on using the repository browser.