LibBSD
LibBSD is a library of FreeBSD code. The origins was a replacement for the Legacy Networking package the project had in the RTEMS Kernel. We do not include networking in the name as libBSD is more than networking. It supports PCIe, USB, eMMC, NVME, and more as well as networking. A goal of libBSD was dealing with the lessons we learned from the Legacy Networking package.
libBSD contains a full featured networking stack that can handle the most demanding system requirements. It is not for small foot print devices. We recommend using lwIP for those targets.
libBSD attempts to keep the source as close to FreeBSD as possible. We preference source transparency over niche optimisations and feature short cuts. libBSD resides in the same address space as RTEMS and application code however we require standard FreeBSD kernel interfaces are used. We do not sneak under the hood to peek or poke data. The porting and maintenance philosophy was discussed in an article published in the FreeBSD Journal.
The ability to use FreeBSD’s code as cleanly as we do is a credit to the FreeBSD team and community. Thanks.
libBSD Repository
The libBSD repository was started by @JoelSherrill in early 2012 with an import of FreeBSD 8.2 sources. Work progressed quickly as functionality from Sebastian Huber and Jennifer Averett as merged. The repository has FreeBSD’s source as a submodule to help maintenance. These original three continued development through in to 2015
Contributors to the project grew. The make based build system was replace by the RTEMS Waf build system and the ability to initialise the system with a scaled back rc.conf was added. The FreeBSD packet filter, media devices and Wifi support were added and the list of supported BSPs and drivers grew.
In 2021 NFSv4 client support was added bringing into libBSD FreeBSD’s VFS support. The Linux kernel had removed NFSv2 and RTEMS needed an NFSv4 client so EPICS systems could interface with these Linux kernels.
The FreeBSD version moved from the initial 8.2 to FreeBSD 12 where is stayed for a period of time. In 2024 Aaron Nyholm brought libBSD up to FreeBSD 14. FreeBSD 13 was never merged in libBSD. The effort brought the project forward by more than 60,000 FreeBSD commits. Aaron then brought the libBSD main branch up to FreeBSD CURRENT merging another 8.000 commits.
The project is active and contributions are always welcomed.
libBSD Releases
libBSD tracks FreeBSD release branches as a separate branches in the source repository and these branches are further defined by the version of RTEMS supported. For example FreeBSD 14 for RTEMS 7 is 7-freebsd-14. This structure lets us release different versions of FreeBSD for a given version of RTEMS. Users can choose to stay with a version of RTEMS and FreeBSD or they can upgrade the version of FreeBSD.
The first release of libBSD was libBSD 5.1 based on FreeBSD 12. The branch is 5-freebsd-12. RTEMS 6.1 was released with libBSD 6.1 from the 6-freebsd-12 branch. RTEMS 6.2 was released after libBSD was updated to FreeBSD 14 and it has libBSD 6.2 based on FreeBSD 12 plus LibBSD 6.2 FB14 based on FreeBSD 14 and the 6-freebsd-14 branch. RTEMS 7 support starts with FreeBSD 14 and the 7-freebsd-14. FreeBSD 15 will be released with RTEMS 7 if it is available.
This release process provides continuity of libBSD versions and features across different versions of RTEMS.
IMPORTANT
We recommend using FreeBSD 14 or later releases for all new projects and for any older projects on RTEMS 6 to update to LibBSD 6.2 FB14. We provide libBSD 6.2 for projects needing an updated RTEMS release.
The Details
Types
FreeBSD and RTEMS can vary in the target architecture supported. libBSD builds for a number of architectures and instruction sets FreeBSD does not. The size of the types needs careful attention. Management of the base types is a constant battle.
FreeBSD is in the process of dropping support for 32-bit architectures. In the future, this may manifest as type size issues and breakage as libBSD is upgraded to newer FreeBSD versions.
A Single Address Space
libBSD contains FreeBSD kernel code, FreeBSD user code and RTEMS glue code called rtemsbsd. This is a complex combination of code and it needs careful separation of the pieces to avoid symbol conflicts or overloading.
The build system separates the sources in to kernel and user files and symbols from kernel sources have _bsd_ prepended. It also manages the include paths to ensure the correct interfaces are used. For example FreeBSD kernel as a malloc() call with a different function signature to the malloc() call in libc.
User Commands
We have ported a number of FreeBSD commands to libBSD. For example ifconfig and netstat. These commands normally run in a separate process address space freshly initialised each time it is run. The code in these commands can make calls to exit() however on RTEMS a call to exit() will cause the system to reboot. Sebastian Huber wrote a framework to support commands so global data does not clash with other commands or application code and calls that cannot be called are redirected. This is a refinement of work done in porting BSD commands to the RTEMS shell.
Newlib Header Files
Newlib has a number of FreeBSD header files. These are used in various parts of RTEMS. We need to keep this list as small as possible as FreeBSD can change these files from time to time complicating building different FreeBSD versions for an RTEMS release.
Every network stack is built against the header files from Newlib. This ensures user applications using a network stack can move to another without impact to the source code.