Legacy Networking
The name Legacy Networking refers to RTEMS’s first networking stack contributed to the project by Eric Norum around 2000. The code used is based the FreeBSD networking stack from that time and while it has had a number of small bug fixes over the last 25 years it has remand largely unchanged.
Eric added networking to RTEMS to support EPICS. At the time RTEMS did not have any networking support. The FreeBSD port was his third attempt to add networking. The first was a port of the KA9Q stack around late 1997 however this was dropped due to licensing reasons. The second attempt was a port of the Linux kernel’s networking stack and that was also dropped because of licensing reasons. FreeBSD was suggested as it provided a proven and stable networking solution with the features you expect with a suitable license.
The legacy networking sources lived in the RTEMS kernel repository and were built into a library called libnetworking.a when the kernel was built. The build system configuration option --enable-networking built the code for BSPs that had networking support. Networking drivers lived in the driver section of a BSP or BSP family.
The work Eric did for the project was ground breaking and an amazing effort and we are still in debit to him for the contributions he made.
IMPORTANT
We do not recommend the Legacy Networking package for any new developments. The source in that repository are kept building with current RTEMS releases to allow long term projects that depend on this software to use current RTEMS release while they migrate to LibBSD. The maintenance work is limited to building and some testing. No bug fixes or features are being worked on.
Legacy Networking Repository
The sources where moved from the RTEMS repository by Vijay Banerjee in early 2021 to the rtems-net-legacy repository.
The networking sources in the RTEMS project could not live there any longer because it:
- Gave users the impression it was a current and maintained networking solution for RTEMS.
- Added build configure complexity.
- Add complexity obsoleting old BSPs.
Sources
The sources started as a copy of FreeBSD sources. The files where moved to a simpler directory structure and they contains edits including white space changes. These factors made tracking and merging any upstream FreeBSD changes difficult and as time went on it became impossible.
The stack initialization was typical of embedded systems then and today. A table of fields set with values or pointers to calls such as drivers or BOOTP and a single call to initialize. Static set ups set variables linked deep into the networking to set default routes or IP addresses.
Support for a range of standard network API interfaces such as socket() provided a good base to port a range of complex networking software.
The stack came with a custom set of RTEMS shell commands that provided useful networking information however no ability to configure or manage the stack while it was running.
The stack predated a working version of IPv6.
Runtime and Drivers
The networking stack used a single lock to protect its internal data. Calls to the stack would obtain the lock and queue or fetch any data and then wake the networking task to complete any work required. There was a single networking task that run the stack’s internal operations such as a timeouts or ping requests. A network driver contained two tasks, a receiving task and a transmitting task. A driver’s interrupt woke its receiving task and it handled the hardware specifics queuing any received data in the stack before waking the networking task. The network task would queue any output data on the driver’s output queue and wake its transmitting task which feed the data to the hardware. All networking tasks shared the same priority.
This tasking environment does not scale well with multiple network interfaces or multi-core SMP systems. FreeBSD has since moved to fine grain locking and a multi-threading kernel and that is now available in LibBSD.
Networking drivers were all custom and specific to RTEMS and the Legacy Network stack. This type of driver development was practical at the time as the number of available networking drivers RTEMS user needed was limited.
Lessons Learnt
As time went on we learnt some basic lessons on how to manage complex and large 3rd party code we use in RTEMS:
- Maintain source transparency. Source transparency is a term we use to say how close to the upstream source a single file or set of files is. A fully transparent file is an exact copy and this is the best outcome as it can be easily updated from the upstream project.
- Maintain the same directory structure adding, removing and moving files as the upstream project does.
- Use a standard preprocessor define and method for any changes to upstream code. This allows you to see what is a local change.
- Do not make any white space changes.
- Follow and use the upstream projects set up and management processes and tools where possible.
- Contribute fixes and improvement back to the upstream project.
- Use upstream drivers.
These lessons have been formalized in the RTEMS Engineering Manual and the outcome is the LibBSD package.