source: rtems-libbsd/libbsd.txt @ b3d1e6a

5-freebsd-12
Last change on this file since b3d1e6a was b3d1e6a, checked in by Christian Mauderer <christian.mauderer@…>, on Mar 21, 2018 at 8:23:17 AM

config.inc: Remove unused values.

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