source: rtems-libbsd/libbsd.txt @ 2707771

55-freebsd-126-freebsd-12
Last change on this file since 2707771 was 2707771, checked in by Sebastian Huber <sebastian.huber@…>, on 09/21/18 at 08:23:08

libbsd.txt: Avoid explicit versions

Update #3472.

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