source: rtems-libbsd/libbsd.txt @ 4c086a2

55-freebsd-126-freebsd-12
Last change on this file since 4c086a2 was 9bc7b96, checked in by Christian Mauderer <christian.mauderer@…>, on 08/06/18 at 05:37:22

libbsd.txt: Update version info and manpage links.

The information is clearly outdated. This patch updates it to the latest
release.

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