Howto for Companies to interacting with LEDE

This guide is targeted at chip vendors, board manufacturers, OEMs and similar companies that want to provide upstream LEDE support for their SoC or board. This will probably also be helpful when selecting a board or SoCs with good LEDE support. The LEDE development model and contribution guidelines are similar to the guidelines of the upstream Linux kernel. (See The Source Code for more technical details)

LEDE is a community project run by a group of people and not by a single company. The advantage is that LEDE is not tied to one specific board, SoC or vendor and supports SoCs and boards from different vendors and is easily to be ported to other platforms.

LEDE provides a common configuration interface over all supported SoCs. The SoC specific drivers should implement the standard, not deprecated, interfaces in the upstream Linux kernel to expose the functionality of the hardware. Using a character device with a vendor specific protocol on top of it or using some vendor defined ioctls is not a standard Linux interface. For Wifi driver this is for example the nl80211 interface provided through cfg80211 or mac80211, without the need of vendor extensions. For switch drivers it is the new switchdev framework, where support in LEDE is planned for.

Every application which is running on the main application CPU in LEDE has to be Open Source to be integrated into upstream LEDE, this includes every user space application and every driver. LEDE does not specify any specific license, it should be any OSI approved license, which is compatible to the code linked against. The code has to be Open Source to make it possible for people not working for the chip vendor or its customers being able to do modifications to the code. These modifications are needed for example when the kernel version gets changed in LEDE, someone finds a bug and wants to fix it, or someone wants to add a new feature to the driver which is missing. LEDE supports the hardware normally as long as people are using the specific hardware, not as long as it gets sold. Some devices which are still being supported in LEDE were introduced more than 10 years ago to the market and are long end of life from the board and SoC vendor perspective.

It is allowed to have a binary only firmware as long as it is not running in the same context as the Linux kernel or as a user space application. This could be a firmware running in the Wifi chip for example. When this firmware has to be loaded into the chip by the driver, which is the case for most firmware binaries, then this firmware has to be published under a license that allows the redistribution of the binary by LEDE and anybody else. Some examples of such licenses can be found here: Intel iwlwifi firmware License. For LEDE the same rules are applying as for the linux-firmware repository. It is preferred to have a device which does not need a firmware and does all the non time critical operations in the driver to be easily modifiable. If a firmware is needed it would be good to also open source the firmware to make it possible for everyone to extend it and to fix bugs in the firmware. Good examples for a wifi driver is the ath9k driver.

It has to be easy to update to a more recent major kernel version. When the next LEDE version is in development more than one kernel version is supported and the target can choose which one to use, in most cases the Linux kernel versions released in the last year are supported. For every release all supported SoCs have to be upgraded to a common, recent kernel version, this is normally the latest major version of the Linux kernel when LEDE starts the big feature freeze. The Linux kernel minor version updates are constantly applied after they are released to get the most recent bugfixes and security patches for the kernel. No supported target will stay for more than one year at the same kernel version. If no one is interested in updating the target to a new major Linux kernel version it will not be included in the next release.

[TODO: do we have a generic article for this] LEDE tries to do one release every 12 months. This starts with a big feature freeze for 1 to 2 months in which no big changes to LEDE trunk, the main development branch, are allowed. After that a new release branch gets created and only bug fixes are allowed, but no new features. It takes an additional 1 to 2 months to get tested by the community in various scenarios and stabilized before the final version gets release. In this process some beta and rc releases are done to make it easier for the community to test the next release. Some months after the final stable release a .1 release is done with the security fixes and bug fixes that were found after the release. The release branch gets bug fixes and security updates till the next release, after that only critical security fixes will be backported. When a security problem in a package is found it is fixed in trunk and also some release branches and new packages are being build and published so users can install a fixed version. All changes that should be applied to a release branch have to be applied to trunk first and then backported to make sure all fixes are also in trunk.

There are different ways to contribute support for a new device by adding a new driver or extending an existing driver. In general LEDE prefers if the driver also gets send for inclusion into the upstream Linux kernel. This has the advantage that the driver automatically gets adapted to changes in kernel APIs which are often done by the same author that did the changes to the API. This reduces the effort needed to upgrade LEDE to a new major kernel version. If the driver is included in upstream Linux kernel the code will be available in LEDE soon, because LEDE updates to the most recent major version of the Linux kernel pretty soon. If a change for the Linux kernel was accepted by the Linux upstream community, it is normally no problem to get a backported version of this change accepted for integration in LEDE, normally no changes are requested in the LEDE code review for such backporteds. It is also possible to submit a driver to be included into LEDE directly without it being include into the upstream Linux kernel. LEDE still prefers if this driver meets the quality requirements of the upstream Linux kernel.

Having a operating system abstraction layer around the driver and not directly using the in kernel API will not allow it to be integrated into the upstream Linux kernel and will also cause problems when integration into OpenWrt. Also when having an own implementations of common features like firmware loading from userspace into the driver instead of using the framework provided by the Linux kernel will cause problems in the code review for LEDE inclusion and has to be changed when it should be added to mainline Linux kernel. The driver should not have build time options to work with either the one chip or the other. Whenever possible it should automatically probe for the hardware and detect if the hardware it supports is there and which chip this is at runtime. If it is possible to have more than one instance of this device connected to a SoC like it is the case on a PCIe card the driver should work with multiple devices and the number should be detected at runtime. Runtime detection could be done based on PCI IDs, device tree and so on. it has to be possible to run the same binary kernel on all boards using the same SoC, it is preferred if the same binary can also be used for different SoCs, which is the case for most SoCs supported by LEDE.

Before a driver or any code from an external contributer is added into upstream LEDE it has to be send to the public mailing list to get reviewed by the community. This is similar to contributing to the Linux kernel. Be aware that your changes will probably not get accepted as is, especially if this is the first contribution and your engineers are not so used to submitting their changes to upstream LEDE. It is normal that the first version does not get accepted and more iterations are needed. This code review does not only check if the use cases you think are important are somehow working, but also also if the code looks correct and uses the correct API in a correct way.

release early, release often

The code adding support for a new chip should be submitted earlier even if it only supports an early chip version which will not get in mass production, or it still misses many features. This way there will be less problems with internal deadlines when the code review takes longer than expected or when some changes to the architecture of the driver are found and required in the code review before it will be merged into upstream LEDE. When the some bigger changes to the architecture of the driver are requested in the code review it is easier to implement them, when the driver is still small and not all features are implemented compared to when it is internally marked as ready and was fully tested. It is no problem to fix bugs or add features to a driver later on, but they also have to get reviewed. It is sufficient if support for a SoC is submitted to LEDE when it only boots up with one core and Ethernet is working and 80% of the other functionality is not yet working.

If help is needed questions can be asked on the public mailing list and probably someone will answer. Please describe your problem as detailed as possible and what LEDE version with which modifications you are running on which hardware. The question and the answer will be in the public. If you have a specific SoC you are looking at, please also mention the SoC name or at least the vendor name in the first mail and tell us that you would pay for these services.