source: rtems-libbsd/libbsd.txt

5-freebsd-12
Last change on this file was a25e6a9, checked in by Sebastian Huber <sebastian.huber@…>, on Sep 21, 2018 at 8:25:18 AM

libbsd.txt: Use rtems_bsd_ifconfig_lo0()

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