source: rtems-libbsd/libbsd.txt @ 1bb23f0

55-freebsd-126-freebsd-12freebsd-9.3
Last change on this file since 1bb23f0 was 1bb23f0, checked in by Sebastian Huber <sebastian.huber@…>, on 06/09/16 at 11:55:48

libbsd.txt: Fix format

  • 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
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.11.  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/realview_pbx_a9_qemu` BSP for
90our internal testing purposes:
91
92-------------------------------------------------------------------------------
93#!/bin/sh
94
95cd ${HOME}/sandbox
96rm -rf b-realview_pbx_a9_qemu
97mkdir b-realview_pbx_a9_qemu
98cd b-realview_pbx_a9_qemu
99${HOME}/git-rtems/configure \
100        --prefix=${HOME}/sandbox/install \
101        --target=arm-rtems4.11 \
102        --enable-rtemsbsp=realview_pbx_a9_qemu \
103        --disable-networking && \
104        make && \
105        make install
106-------------------------------------------------------------------------------
107
108The `arm/realview_pbx_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.11
130BSP = realview_pbx_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
388Make sure that each Qemu instance uses its own MAC address to avoid an address
389conflict (or otherwise use it as a test).
390
391To connect the Qemu instances with your local network use the following
392(replace 'eth0' with the network interface of your host).
393
394-------------------------------------------------------------------------------
395ifconfig eth0 0.0.0.0
396brctl addif qbri eth0
397dhclient qbri
398-------------------------------------------------------------------------------
399
400== Issues and TODO
401
402* PCI support on x86 uses a quick and dirty hack, see pci_reserve_map().
403
404* Priority queues are broken with clustered scheduling.
405
406* Per-CPU data should be enabled once the new stack is ready for SMP.
407
408* Per-CPU NETISR(9) should be enabled onece the new stack is ready for SMP.
409
410* Multiple routing tables are not supported.  Every FIB value is set to zero
411  (= BSD_DEFAULT_FIB).
412
413* Process identifiers are not supported.  Every PID value is set to zero
414  (= BSD_DEFAULT_PID).
415
416* User credentials are not supported.  The following functions allow the
417  operation for everyone
418  - prison_equal_ip4(),
419  - chgsbsize(),
420  - cr_cansee(),
421  - cr_canseesocket() and
422  - cr_canseeinpcb().
423
424* A basic USB functionality test that is known to work on Qemu is desirable.
425
426* Adapt generic IRQ PIC interface code to Simple Vectored Interrupt Model
427  so that those architectures can use new TCP/IP and USB code.
428
429* freebsd-userspace/rtems/include/sys/syslog.h is a copy from the old
430  RTEMS TCP/IP stack. For some reason, the __printflike markers do not
431  compile in this environment. We may want to use the FreeBSD syslog.h
432  and get this addressed.
433
434* in_cksum implementations for architectures not supported by FreeBSD.
435  This will require figuring out where to put implementations that do
436  not originate from FreeBSD and are populated via the script.
437
438* MAC support functions are not thread-safe ("freebsd/lib/libc/posix1e/mac.c").
439
440* IFCONFIG(8): IEEE80211 support is disabled.  This module depends on a XML
441  parser and mmap().
442
443* get_cyclecount(): The implementation is a security problem.
444
445* What to do with the priority parameter present in the FreeBSD synchronization
446  primitives and the thread creation functions?
447
448* TASKQUEUE(9): Support spin mutexes.
449
450* ZONE(9): Review allocator lock usage in rtems-bsd-chunk.c.
451
452* KQUEUE(2): Choose proper lock for global kqueue list.
453
454* TIMEOUT(9): Maybe use special task instead of timer server to call
455  callout_tick().
456
457* sysctl_handle_opaque(): Implement reliable snapshots.
458
459* PING6(8): What to do with SIGALARM?
460
461* <sys/param.h>: Update Newlib to use a MSIZE of 256.
462
463* BPF(4): Add support for zero-copy buffers.
464
465* UNIX(4): Fix race conditions in the area of socket object and file node
466  destruction.  Add support for file descriptor transmission via control
467  messages.
468
469* PRINTF(9): Add support for log(), the %D format specifier is missing in the
470  normal printf() family.
471
472* Why is the interrupt server used?  The BSD interrupt handlers can block on
473synchronization primitives like mutexes.  This is in contrast to RTEMS
474interrupt service routines.  The BSPs using the generic interrupt support must
475implement the `bsp_interrupt_vector_enable()` and
476`bsp_interrupt_vector_disable()` routines.  They normally enable/disable a
477particular interrupt source at the interrupt controller.  This can be used to
478implement the interrupt server.  The interrupt server is a task that wakes-up
479in case an associated interrupt happens.  The interrupt source is disabled in
480a generic interrupt handler that wakes-up the interrupt server task.   Once the
481postponed interrupt processing is performed in the interrupt server the
482interrupt source is enabled again.
483
484* Convert all BSP linkcmds to use a linkcmds.base so the sections are
485easier to insert.
486
487* NIC Device Drivers
488- Only common PCI NIC drivers have been included in the initial set. These
489do not include any system on chip or ISA drivers.
490- PCI configuration probe does not appear to happen to determine if a
491NIC is in I/O or memory space. We have worked around this by using a
492static hint to tell the fxp driver the correct mode. But this needs to
493be addressed.
494- The ISA drivers require more BSD infrastructure to be addressed. This was
495outside the scope of the initial porting effort.
496
497== FreeBSD Source
498
499You should be able to rely on FreebSD manual pages and documentation
500for details on the code itself.
501
502=== Automatically Generated FreeBSD Files
503
504Some source and header files are automatically generated during the FreeBSD
505build process.  The `Makefile.todo` file performs this manually.  The should be
506included in `freebsd-to-rtems.py` script some time in the future.  For details,
507see also
508http://www.freebsd.org/cgi/man.cgi?query=kobj&sektion=9&apropos=0&manpath=FreeBSD+9.2-RELEASE[KOBJ(9)].
509
510=== Rules for Modifying FreeBSD Source
511
512Only add lines.  If your patch contains lines starting with a '-', then this is
513wrong.  Subtract code by added `#ifndef __rtems__`.  This makes merging easier
514in the future.  For example:
515
516-------------------------------------------------------------------------------
517/* Global variables for the kernel. */
518
519#ifndef __rtems__
520/* 1.1 */
521extern char kernelname[MAXPATHLEN];
522#endif /* __rtems__ */
523
524extern int tick;                        /* usec per tick (1000000 / hz) */
525-------------------------------------------------------------------------------
526
527-------------------------------------------------------------------------------
528#if defined(_KERNEL) || defined(_WANT_FILE)
529#ifdef __rtems__
530#include <rtems/libio_.h>
531#include <sys/fcntl.h>
532#endif /* __rtems__ */
533/*
534 * Kernel descriptor table.
535 * One entry for each open kernel vnode and socket.
536 *
537 * Below is the list of locks that protects members in struct file.
538 *
539 * (f) protected with mtx_lock(mtx_pool_find(fp))
540 * (d) cdevpriv_mtx
541 * none not locked
542 */
543-------------------------------------------------------------------------------
544
545-------------------------------------------------------------------------------
546extern int profprocs;                   /* number of process's profiling */
547#ifndef __rtems__
548extern volatile int ticks;
549#else /* __rtems__ */
550#include <rtems/score/watchdogimpl.h>
551#define ticks _Watchdog_Ticks_since_boot
552#endif /* __rtems__ */
553
554#endif /* _KERNEL */
555-------------------------------------------------------------------------------
556
557Add nothing (even blank lines) before or after the `__rtems__` guards.  Always
558include a `__rtems__` in the guards to make searches easy, so use
559
560* `#ifndef __rtems__`,
561* `#ifdef __rtems__`,
562* `#else /* __rtems__ */`, and
563* `#endif /* __rtems__ */`.
564
565For new code use
566http://www.freebsd.org/cgi/man.cgi?query=style&apropos=0&sektion=9&manpath=FreeBSD+9.2-RELEASE&arch=default&format=html[STYLE(9)].
567Do not format original FreeBSD code.
568
569== BSD Library Source
570
571=== What is in the Git Repository
572
573There is a self-contained kit with FreeBSD and RTEMS components pre-merged. The
574Waf wscript in this kit is automatically generated.
575
576Any changes to source in the `freebsd` directories will need to be merged
577upstream into our master FreeBSD checkout, the `freebsd-org` submodule.
578
579The repository contains two FreeBSD source trees.  In the `freebsd` directory
580are the so called 'managed' FreeBSD sources used to build the BSD library.  The
581FreeBSD source in `freebsd-org` is the 'master' version.  The
582`freebsd-to-rtems.py` script is used to transfer files between the two trees.
583In general terms, if you have modified managed FreeBSD sources, you will need
584to run the script in 'revert' or 'reverse' mode using the `-R` switch.  This
585will copy the source back to your local copy of the master FreeBSD source so
586you can run `git diff` against the upstream FreeBSD source.  If you want to
587transfer source files from the master FreeBSD source to the manged FreeBSD
588sources, then you must run the script in 'forward' mode (the default).
589
590=== Organization
591
592The top level directory contains a few directories and files. The following
593are important to understand
594
595* `freebsd-to-rtems.py` - script to convert to and free FreeBSD and RTEMS trees,
596* `create-kernel-namespace.sh` - script to create the kernel namespace header <machine/rtems-bsd-kernel-namespace.h,
597* `wscript` - automatically generated,
598* `freebsd/` - from FreeBSD by script,
599* `rtemsbsd/` - RTEMS specific implementations of FreeBSD kernel support routines,
600* `testsuite/` - RTEMS specific tests, and
601* `libbsd.txt` - documentation in Asciidoc.
602
603== Moving Code Between Managed and Master FreeBSD Source
604
605The script `freebsd-to-rtems.py` is used to copy code from FreeBSD to the
606rtems-libbsd tree and to reverse this process. This script attempts to
607automate this process as much as possible and performs some transformations
608on the FreeBSD code. Its command line arguments are shown below:
609
610----
611freebsd-to-rtems.py [args]
612  -?|-h|--help      print this and exit
613  -d|--dry-run      run program but no modifications
614  -D|--diff         provide diff of files between trees
615  -e|--early-exit   evaluate arguments, print results, and exit
616  -m|--makefile     Warning: depreciated and will be removed
617  -b|--buildscripts just generate the build scripts
618  -S|--stats        Print a statistics report
619  -R|--reverse      default FreeBSD -> RTEMS, reverse that
620  -r|--rtems        RTEMS Libbsd directory (default: '.')
621  -f|--freebsd      FreeBSD SVN directory (default: 'freebsd-org')
622  -v|--verbose      enable verbose output mode
623----
624
625In its default mode of operation, freebsd-to-rtems.py is used to copy code
626from FreeBSD to the rtems-libbsd tree and perform transformations.  In forward
627mode, the script may be requested to just generate the Waf script.
628
629In "reverse mode", this script undoes those transformations and copies
630the source code back to the FreeBSD SVN tree. This allows us to do
631'svn diff', evaluate changes made by the RTEMS Project, and report changes
632back to FreeBSD upstream.
633
634In either mode, the script may be asked to perform a dry-run or be verbose.
635Also, in either mode, the script is also smart enough to avoid copying over
636files which have not changed. This means that the timestamps of files are
637not changed unless the contents change. The script will also report the
638number of files which changed. In verbose mode, the script will print
639the name of the files which are changed.
640
641To add or update files int the RTEMS FreeBSD tree first run the 'reverse mode'
642and move the current set of patches FreeBSD. The script may warn you if a file
643is not present at the destination for the direction. This can happen as files
644not avaliable at the FreeBSD snapshot point have been specially added to the
645RTEMS FreeBSD tree. Warnings can also appear if you have changed the list of
646files in libbsd.py. The reverse mode will result in the FreeBSD having
647uncommitted changes. You can ignore these. Once the reverse process has
648finished edit libbsd.py and add any new files then run the forwad mode to bring
649those files into the RTEMS FreeBSD tree.
650
651The following is an example forward run with no changes.
652
653----
654$ ~/newbsd/git/libbsd-8.2/freebsd-to-rtems.py \
655    -r /home/joel/newbsd/git/libbsd-8.2 \
656    -f /home/joel/newbsd/libbsd/freebsd-8.2 -v
657Verbose:                yes (1)
658Dry Run:                no
659Only Generate Makefile: no
660RTEMS Directory:        /home/joel/newbsd/git/libbsd-8.2
661FreeBSD Directory:      /home/joel/newbsd/libbsd/freebsd-8.2
662Direction:              forward
663Generating into /home/joel/newbsd/git/libbsd-8.2
6640 files were changed.
665----
666
667The script may also be used to generate a diff in either forward or reverse
668direction.
669
670You can add more than one verbose option (-v) to the command line and get more
671detail and debug level information from the command.
672
673== How to import code from FreeBSD
674
675. Run `git status` and make sure your working directory is clean.
676. Run `./freebsd-to-rtems.py -R`
677. Run `./freebsd-to-rtems.py`
678. 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.
679. Add the files to import to `libbsd.py`.
680. Run `./freebsd-to-rtems.py`
681. Immediately check in the imported files without the changes to `libbsd_waf.py`.  Do not touch the imported files yourself at this point.
682. Port the imported files to RTEMS.  See 'Rules for Modifying FreeBSD Source'.
683. Add a test to the testsuite if possible.
684. 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`.
685. Create one commit from this.
686
687The -S or --stats option generates reports the changes we have made to
688FreeBSD. If the code has been reserved into the original FreeBSD tree it will
689show nothing has changed. To see what we have change:
690
691 $ cd freebsd-org
692 $ git checkout -- .
693 $ cd ..
694 $ ./freebsd-to-rtems.py -R -S -d
695
696The report lists the files change based on the opacity level. The opacity is a
697measure on how much of a file differs from the original FreeBSD source. The
698lower the value the more transparent the source file it.
699
700== Initialization of the BSD Library
701
702The initialization of the BSD library is based on the FreeBSD SYSINIT(9)
703infrastructure.  The key to initializing a system is to ensure that the desired
704device drivers are explicitly pulled into the linked application.  This plus
705linking against the BSD library (`libbsd.a`) will pull in the necessary FreeBSD
706infrastructure.
707
708The FreeBSD kernel is not a library like the RTEMS kernel.  It is a bunch of
709object files linked together.  If we have a library, then creating the
710executable is simple.  We begin with a start symbol and recursively resolve all
711references.  With a bunch of object files linked together we need a different
712mechanism.  Most object files don't know each other.  Lets say we have a driver
713module.  The rest of the system has no references to this driver module.  The
714driver module needs a way to tell the rest of the system: Hey, kernel I am
715here, please use my services!
716
717This registration of independent components is performed by SYSINIT(9) and
718specializations:
719
720http://www.freebsd.org/cgi/man.cgi?query=SYSINIT
721
722The SYSINIT(9) uses some global data structures that are placed in a certain
723section.  In the linker command file we need this:
724
725-------------------------------------------------------------------------------
726.rtemsroset : {
727        KEEP (*(SORT(.rtemsroset.*)))
728}
729
730.rtemsrwset : {
731        KEEP (*(SORT(.rtemsrwset.*)))
732}
733-------------------------------------------------------------------------------
734
735This results for example in this executable layout:
736
737-------------------------------------------------------------------------------
738[...]
739 *(SORT(.rtemsroset.*))
740 .rtemsroset.bsd.modmetadata_set.begin
741                0x000000000025fe00        0x0 libbsd.a(rtems-bsd-init.o)
742                0x000000000025fe00                _bsd__start_set_modmetadata_set
743 .rtemsroset.bsd.modmetadata_set.content
744                0x000000000025fe00        0x8 libbsd.a(rtems-bsd-nexus.o)
745 .rtemsroset.bsd.modmetadata_set.content
746                0x000000000025fe08        0x4 libbsd.a(kern_module.o)
747[...]
748 .rtemsroset.bsd.modmetadata_set.content
749                0x000000000025fe68        0x4 libbsd.a(mii.o)
750 .rtemsroset.bsd.modmetadata_set.content
751                0x000000000025fe6c        0x4 libbsd.a(mii_bitbang.o)
752 .rtemsroset.bsd.modmetadata_set.end
753                0x000000000025fe70        0x0 libbsd.a(rtems-bsd-init.o)
754                0x000000000025fe70                _bsd__stop_set_modmetadata_set
755[...]
756.rtemsrwset     0x000000000030bad0      0x290
757 *(SORT(.rtemsrwset.*))
758 .rtemsrwset.bsd.sysinit_set.begin
759                0x000000000030bad0        0x0 libbsd.a(rtems-bsd-init.o)
760                0x000000000030bad0                _bsd__start_set_sysinit_set
761 .rtemsrwset.bsd.sysinit_set.content
762                0x000000000030bad0        0x4 libbsd.a(rtems-bsd-nexus.o)
763 .rtemsrwset.bsd.sysinit_set.content
764                0x000000000030bad4        0x8 libbsd.a(rtems-bsd-thread.o)
765 .rtemsrwset.bsd.sysinit_set.content
766                0x000000000030badc        0x4 libbsd.a(init_main.o)
767[...]
768 .rtemsrwset.bsd.sysinit_set.content
769                0x000000000030bd54        0x4 libbsd.a(frag6.o)
770 .rtemsrwset.bsd.sysinit_set.content
771                0x000000000030bd58        0x8 libbsd.a(uipc_accf.o)
772 .rtemsrwset.bsd.sysinit_set.end
773                0x000000000030bd60        0x0 libbsd.a(rtems-bsd-init.o)
774                0x000000000030bd60                _bsd__stop_set_sysinit_set
775[...]
776-------------------------------------------------------------------------------
777
778Here you can see, that some global data structures are collected into
779continuous memory areas.  This memory area can be identified by start and stop
780symbols.  This constructs a table of uniform items.
781
782The low level FreeBSD code calls at some time during the initialization the
783mi_startup() function (machine independent startup).  This function will sort
784the SYSINIT(9) set and call handler functions which perform further
785initialization.  The last step is the scheduler invocation.
786
787The SYSINIT(9) routines are run in mi_startup() which is called by
788rtems_bsd_initialize().
789
790This is also explained in "The Design and Implementation of the FreeBSD
791Operating System" section 14.3 "Kernel Initialization".
792
793In RTEMS we have a library and not a bunch of object files.  Thus we need a way
794to pull-in the desired services out of the libbsd.  Here the
795`rtems-bsd-sysinit.h` comes into play.  The SYSINIT(9) macros have been
796modified and extended for RTEMS in `<sys/kernel.h>`:
797
798-------------------------------------------------------------------------------
799#ifndef __rtems__
800#define C_SYSINIT(uniquifier, subsystem, order, func, ident)    \
801        static struct sysinit uniquifier ## _sys_init = {       \
802                subsystem,                                      \
803                order,                                          \
804                func,                                           \
805                (ident)                                         \
806        };                                                      \
807        DATA_SET(sysinit_set,uniquifier ## _sys_init)
808#else /* __rtems__ */
809#define SYSINIT_ENTRY_NAME(uniquifier)                          \
810        _bsd_ ## uniquifier ## _sys_init
811#define SYSINIT_REFERENCE_NAME(uniquifier)                      \
812        _bsd_ ## uniquifier ## _sys_init_ref
813#define C_SYSINIT(uniquifier, subsystem, order, func, ident)    \
814        struct sysinit SYSINIT_ENTRY_NAME(uniquifier) = {       \
815                subsystem,                                      \
816                order,                                          \
817                func,                                           \
818                (ident)                                         \
819        };                                                      \
820        RWDATA_SET(sysinit_set,SYSINIT_ENTRY_NAME(uniquifier))
821#define SYSINIT_REFERENCE(uniquifier)                           \
822        extern struct sysinit SYSINIT_ENTRY_NAME(uniquifier);   \
823        static struct sysinit const * const                     \
824        SYSINIT_REFERENCE_NAME(uniquifier) __used               \
825        = &SYSINIT_ENTRY_NAME(uniquifier)
826#define SYSINIT_MODULE_REFERENCE(mod)                           \
827        SYSINIT_REFERENCE(mod ## module)
828#define SYSINIT_DRIVER_REFERENCE(driver, bus)                   \
829        SYSINIT_MODULE_REFERENCE(driver ## _ ## bus)
830#define SYSINIT_DOMAIN_REFERENCE(dom)                           \
831        SYSINIT_REFERENCE(domain_add_ ## dom)
832#endif /* __rtems__ */
833-------------------------------------------------------------------------------
834
835Here you see that the SYSINIT(9) entries are no longer static.  The
836\*_REFERENCE() macros will create references to the corresponding modules which
837are later resolved by the linker.  The application has to provide an object
838file with references to all required FreeBSD modules.
839
840The FreeBSD device model is quite elaborated (with follow-ups):
841
842http://www.freebsd.org/cgi/man.cgi?query=driver
843
844The devices form a tree with the Nexus device at a high-level.  This Nexus
845device is architecture specific in FreeBSD.  In RTEMS we have our own Nexus
846device, see `rtemsbsd/bsp/bsp-bsd-nexus-devices.c`.
847
848=== SYSCTL_NODE Example
849
850During development, we had an undefined reference to
851_bsd_sysctl__net_children that we had trouble tracking down. Thanks to
852Chris Johns, we located it. He explained how to read SYSCTL_NODE
853definitions. This line from freebsd/netinet/in_proto.c is attempting
854to add the "inet" node to the parent node "_net".
855
856----
857SYSCTL_NODE(_net,      PF_INET,         inet,   CTLFLAG_RW, 0,
858        "Internet Family");
859----
860
861Our problem was that we could not find where _bsd_sysctl__net_children
862was defined. Chris suggested that when in doubt compile with -save-temps
863and look at the preprocessed .i files. But he did not need that. He
864explained that this the symbol name _bsd_sysctl__net_children was
865automatically generated by a SYSCTL_NODE as follows:
866
867* _bsd_ - added by RTEMS modifications to SYSCTL_NODE macro
868* sysctl_ - boilerplace added by SYSCTL_NODE macro
869* "" - empty string for parent node
870* net - name of SYSCTL_NODE
871* children - added by SYSCTL macros
872
873This was all generated by a support macro declaring the node as this:
874
875----
876struct sysctl_oid_list SYSCTL_NODE_CHILDREN(parent, name);
877----
878
879Given this information, we located this SYSCTL_NODE declaration in
880kern/kern_mib.c
881
882----
883SYSCTL_NODE(, CTL_KERN,   kern,   CTLFLAG_RW, 0,
884        "High kernel, proc, limits &c");
885----
886
887== Core FreeBSD APIs and RTEMS Replacements ==
888
889=== SX(9) (Shared/exclusive locks) ===
890
891http://www.freebsd.org/cgi/man.cgi?query=sx
892
893Binary semaphores (this neglects the ability to allow shared access).
894
895=== MUTEX(9) (Mutual exclusion) ===
896
897http://www.freebsd.org/cgi/man.cgi?query=mutex
898
899Binary semaphores (not recursive mutexes are not supported this way).
900
901=== RWLOCK(9) (Reader/writer lock) ===
902
903http://www.freebsd.org/cgi/man.cgi?query=rwlock
904
905POSIX r/w lock.
906
907=== RMLOCK(9) (Reader/writer lock optimized for mostly read access patterns) ===
908
909Note:  This object was implemented as a wrapper for RWLOCK in the rm_lock header file.
910
911http://www.freebsd.org/cgi/man.cgi?query=rmlock
912
913POSIX r/w lock.
914
915=== CONDVAR(9) (Condition variables) ===
916
917http://www.freebsd.org/cgi/man.cgi?query=condvar
918
919POSIX condition variables with modifications (hack).
920
921=== CALLOUT(9) (Timer functions) ===
922
923http://www.freebsd.org/cgi/man.cgi?query=callout
924
925Timer server.
926
927=== TASKQUEUE(9) (Asynchronous task execution) ===
928
929http://www.freebsd.org/cgi/man.cgi?query=taskqueue
930
931TBD.
932
933=== KTHREAD(9), KPROC(9) (Tasks) ===
934
935http://www.freebsd.org/cgi/man.cgi?query=kthread
936
937http://www.freebsd.org/cgi/man.cgi?query=kproc
938
939Tasks.
940
941=== ZONE(9) (Zone allocator) ===
942
943http://www.freebsd.org/cgi/man.cgi?query=zone
944
945TBD.
946
947=== devfs (Device file system) ===
948
949Dummy, IMFS or new implementation (currently dummy).
950
951=== psignal (Signals) ===
952
953TBD.  Seems to be not needed.
954
955=== poll, select ===
956
957TBD.  Seems to be not needed.
958
959=== RMAN(9) (Resource management) ===
960
961http://www.freebsd.org/cgi/man.cgi?query=rman
962
963TBD.  Seems to be not needed.
964
965=== DEVCLASS(9), DEVICE(9), DRIVER(9), MAKE_DEV(9) (Device management) ===
966
967http://www.freebsd.org/cgi/man.cgi?query=devclass
968
969http://www.freebsd.org/cgi/man.cgi?query=device
970
971http://www.freebsd.org/cgi/man.cgi?query=driver
972
973http://www.freebsd.org/cgi/man.cgi?query=make_dev
974
975Use FreeBSD implementation as far as possible.  FreeBSD has a nice API for
976dynamic device handling.  It may be interesting for RTEMS to use this API
977internally in the future.
978
979=== BUS_SPACE(9), BUS_DMA(9) (Bus and DMA access) ===
980
981http://www.freebsd.org/cgi/man.cgi?query=bus_space
982
983http://www.freebsd.org/cgi/man.cgi?query=bus_dma
984
985Likely BSP dependent.  A default implementation for memory mapped linear access
986is easy to provide.  The current heap implementation supports all properties
987demanded by bus_dma (including the boundary constraint).
988
989== RTEMS Replacements by File Description ==
990
991Note:  Files with a status of USB are used by the USB test and have at least
992been partially tested.  If they contain both USB and Nic, then they are used
993by both and MAY contain methods that have not been tested yet.  Files that
994are only used by the Nic test are the most suspect.
995
996----
997rtems-libbsd File:      rtems-bsd-assert.c
998FreeBSD File:           rtems-bsd-config.h redefines BSD_ASSERT.
999Description:            This file contains the support method rtems_bsd_assert_func().
1000Status:                 USB, Nic
1001
1002rtems-libbsd File:      rtems-bsd-autoconf.c
1003FreeBSD File:           FreeBSD has BSP specific autoconf.c
1004Description:            This file contains configuration methods that are used to setup the system.
1005Status:                 USB
1006
1007rtems-libbsd File:      rtems-bsd-bus-dma.c
1008FreeBSD File:           FreeBSD has BSP specific busdma_machdep.c
1009Description:
1010Status:                 USB, Nic
1011
1012rtems-libbsd File:      rtems-bsd-bus-dma-mbuf.c
1013FreeBSD File:           FreeBSD has BSP specific busdma_machdep.c
1014Description:
1015Status:                 Nic
1016
1017rtems-libbsd File:      rtems-bsd-callout.c
1018FreeBSD File:           kern/kern_timeout.c
1019Description:
1020Status:                 USB, Nic
1021
1022rtems-libbsd File:      rtems-bsd-cam.c
1023FreeBSD File:           cam/cam_sim.c
1024Description:
1025Status:                 USB
1026
1027rtems-libbsd File:      rtems-bsd-condvar.c
1028FreeBSD File:           kern/kern_condvar.c
1029Description:
1030Status:                 USB
1031
1032rtems-libbsd File:      rtems-bsd-copyinout.c
1033FreeBSD File:           bsp specific copyinout.c )
1034Description:            Note: The FreeBSD file is split with some methods being in rtems-bsd-support
1035Status:                 Nic
1036
1037rtems-libbsd File:      rtems-bsd-delay.c
1038FreeBSD File:           bsp specific file with multiple names
1039Description:
1040Status:                 USB, Nic
1041
1042rtems-libbsd File:      rtems-bsd-descrip.c
1043FreeBSD File:           kern/kern_descrip.c
1044Description:
1045Status:                 Nic
1046
1047rtems-libbsd File:      rtems-bsd-generic.c
1048FreeBSD File:           kern/sys_generic.c
1049Description:
1050Status:                 Nic
1051
1052rtems-libbsd File:      rtems-bsd-init.c
1053FreeBSD File:           N/A
1054Description:
1055Status:                 USB, Nic
1056
1057rtems-libbsd File:      rtems-bsd-init-with-irq.c
1058FreeBSD File:           N/A
1059Description:
1060Status:                 USB, Nic
1061
1062rtems-libbsd File:      rtems-bsd-jail.c
1063FreeBSD File:           kern/kern_jail.c
1064Description:
1065Status:                 USB, Nic
1066
1067rtems-libbsd File:      rtems-bsd-lock.c
1068FreeBSD File:           kern/subr_lock.c
1069Description:
1070Status:                 USB, Nic
1071
1072rtems-libbsd File:      rtems-bsd-log.c
1073FreeBSD File:           kern/subr_prf.c
1074Description:
1075Status:                 Nic
1076
1077rtems-libbsd File:      rtems-bsd-malloc.c
1078FreeBSD File:           kern/kern_malloc.c
1079Description:
1080Status:                 USB, Nic
1081
1082rtems-libbsd File:      rtems-bsd-mutex.c
1083FreeBSD File:           kern/kern_mutex.c
1084Description:
1085Status:                 USB, Nic
1086
1087rtems-libbsd File:      rtems-bsd-newproc.c
1088FreeBSD File:           N/A
1089Description:
1090Status:                 Nic
1091
1092rtems-libbsd File:      rtems-bsd-nexus.c
1093FreeBSD File:           bsp specific nexus.c
1094Description:
1095Status:                 USB
1096
1097rtems-libbsd File:      rtems-bsd-panic.c
1098FreeBSD File:           boot/common/panic.c
1099Description:
1100Status:                 USB, Nic
1101
1102rtems-libbsd File:      rtems-bsd-rwlock.c
1103FreeBSD File:           kern_rwlock.c
1104Description:
1105Status:                 USB, Nic
1106
1107rtems-libbsd File:      rtems-bsd-shell.c
1108FreeBSD File:           N/A
1109Description:
1110Status:                 USB
1111
1112rtems-libbsd File:      rtems-bsd-signal.c
1113FreeBSD File:           kern/kern_sig.c
1114Description:
1115Status:                 Nic
1116
1117rtems-libbsd File:      rtems-bsd-smp.c
1118FreeBSD File:           N/A
1119Description:
1120Status:                 Nic
1121
1122rtems-libbsd File:      rtems-bsd-support.c
1123FreeBSD File:           bsp specific copyinout.c
1124Description:            Note: the FreeBSD file is split with some methods being in rtems-bsd-copyinout.
1125Status:                 USB, Nic
1126
1127rtems-libbsd File:      rtems-bsd-sx.c
1128FreeBSD File:           kern/kern_sx.c
1129Description:            Status: USB, Nic
1130
1131rtems-libbsd File:      rtems-bsd-synch.c
1132FreeBSD File:           kern/kern_synch.c
1133Description:
1134Status:                 USB, Nic
1135
1136rtems-libbsd File:      rtems-bsd-syscalls.c
1137FreeBSD File:           User API for kern/uipc_syscalls.c
1138Description:
1139Status:                 Nic
1140
1141rtems-libbsd File:      rtems-bsd-sysctlbyname.c
1142FreeBSD File:           User API for sysctlbyname(3)
1143Description:
1144Status:
1145
1146rtems-libbsd File:      rtems-bsd-sysctl.c
1147FreeBSD File:           User API for sysctl(8)
1148Description:
1149Status:
1150
1151rtems-libbsd File:      rtems-bsd-sysctlnametomib.c
1152FreeBSD File:           User API for sysctlnametomib
1153Description:
1154Status:
1155
1156rtems-libbsd File:      rtems-bsd-taskqueue.c
1157FreeBSD File:           kern/subr_taskqueue.c
1158Description:
1159Status:                 Nic
1160
1161rtems-libbsd File:      rtems-bsd-thread.c
1162FreeBSD File:           kern/kern_kthread.c
1163Description:
1164Status:                 USB, Nic
1165
1166rtems-libbsd File:      rtems-bsd-timeout.c
1167FreeBSD File:           kern/kern_timeout.c
1168Description:
1169Status:                 Nic
1170
1171rtems-libbsd File:      rtems-bsd-timesupport.c
1172FreeBSD File:           kern/kern_clock.c
1173Description:
1174Status:                 Nic
1175
1176rtems-libbsd File:      rtems-bsd-vm_glue.c
1177FreeBSD File:           vm/vm_glue.c
1178Description:
1179Status:                 USB, Nic
1180----
1181
1182== Notes by File ==
1183
1184altq_subr.c - Arbitrary choices were made in this file that RTEMS would
1185not support tsc frequency change.  Additionally, the clock frequency
1186for machclk_freq is always measured for RTEMS.
1187
1188conf.h - In order to add make_dev and destroy_dev, variables in the cdev
1189structure that were not being used were conditionally compiled out. The
1190capability of supporting children did not appear to be needed and was
1191not implemented in the rtems version of these routines.
1192
1193== NICs Status ==
1194
1195----
1196Driver                  Symbol                          Status
1197======                  ======                          ======
1198RealTek                 _bsd_re_pcimodule_sys_init      Links
1199EtherExpress            _bsd_fxp_pcimodule_sys_init     Links
1200DEC tulip               _bsd_dc_pcimodule_sys_init      Links
1201Broadcom BCM57xxx       _bsd_bce_pcimodule_sys_init     Links
1202Broadcom BCM4401        _bsd_bfe_pcimodule_sys_init     Links
1203Broadcom BCM570x        _bsd_bge_pcimodule_sys_init     Needs Symbols (A)
1204E1000 IGB               _bsd_igb_pcimodule_sys_init     Links
1205E1000 EM                _bsd_em_pcimodule_sys_init      Links
1206Cadence                 ?                               Links, works.
1207----
1208
1209To add a NIC edit rtemsbsd/include/bsp/nexus-devices.h and add the driver
1210reference to the architecture and/or BSP. For example to add the RealTek driver
1211add:
1212
1213SYSINIT_DRIVER_REFERENCE(re, pci);
1214
1215and to add the MII PHY driver add:
1216
1217SYSINIT_DRIVER_REFERENCE(rge, miibus);
1218
1219The PC BSP has these entries.
1220
1221Symbols (A)
1222         pci_get_vpd_ident
1223
1224=== Cadence ===
1225
1226The cadence driver works on the Xilinx Zynq platform. The hardware checksum
1227support works on real hardware but does not seem to be supported on qemu
1228therefore the default state is to disable TXCSUM and RXCSUM and this can be
1229enabled from the shell with:
1230
1231  # ifconfig cgem0 rxcsum txcsum
1232
1233or with an ioctl call to the network interface driver with SIOCSIFCAP and the
1234mask IFCAP_TXCSUM and IFCAP_RXCSUM set.
1235
1236== Problems to report to FreeBSD ==
1237
1238The MMAP_NOT_AVAILABLE define is inverted on its usage.  When it is
1239defined the mmap method is called. Additionally, it is not used
1240thoroughly. It is not used in the unmap portion of the source.
1241The file rec_open.c uses the define MMAP_NOT_AVAILABLE to wrap
1242the call to mmap and file rec_close.c uses the munmap method.
Note: See TracBrowser for help on using the repository browser.