source: rtems-libbsd/libbsd.txt @ f9798ad

55-freebsd-126-freebsd-12freebsd-9.3
Last change on this file since f9798ad was f9798ad, checked in by Chris Johns <chrisj@…>, on 05/30/16 at 23:49:31

Add a stats report command.

The report shows the level of changes we have made to the FreeBSD code.

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