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

5-freebsd-12freebsd-9.3
Last change on this file since 9edacb6 was 9edacb6, checked in by Chris Johns <chrisj@…>, on Jun 27, 2016 at 3:12:39 AM

Fix spelling.

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