Adding support for your hardware to OpenWrt

From PRPL
Jump to: navigation, search

Adding support for your hardware to OpenWrt follows a process that is quite common in open source for accepting changes. At the same time, this process may be somewhat foreign to folks used to software development inside a company. It's important to understand, respect and fulfill the needs of the OpenWrt and Linux community. This page lists a number of tips that a driver creator could follow to make inclusion of their driver as smooth and rapid as possible.

Maintain legacy hardware[edit]

The first tip is to "maintain legacy hardware." As much as you may want to focus on your new, shiny hardware, it's important to not ignore your legacy hardware. Open source developers have minimal time to focus on fixing problems, providing support and managing patch proposals. They have to prioritize tasksand part of that prioritization is considering how much work and headache accepting a changeset will cause them. When a company stops supporting legacy hardware, that means they have to handle bug reports, user complaints and deal with broken behavior if they use it themselves. That's additional work for the maintainer and they will consider that when they look at your patch.

Making sure your legacy hardware is supported over time is an important way to build credibility in the community. Additionally, your patches are more likely to be evaluated quickly for your newer hardware as well. Daniel Lezcano, a kernel maintainer, uses the metaphor of a garden to illustrate open source expectations on legacy hardware support:

"[The open source space] could be seen as a big public garden, where everyone can plant flowers. The people in the garden, being there a long time, know what kind of flowers you can plant without interacting badly with the existing flowers in the garden and where you can plant them. If the people in the garden like your flowers, they can point you to a place where you can put the flowers and also they may help you to do this if they want. Those people expect you to take care of your flowers after you have planted them and as they helped you to plant the flowers, they also expect you to help in return. If a group of people is not willing to follow the rules of the public garden and just want to plant flowers because they have to (e.g. because their boss put a ticket office near the south entrance of the garden and they want the public garden to be more attractive from there), the key keepers of the garden will just come and close the gates to those people."

To use Daniel's metaphor, if you plant flowers in the public garden, you need to make sure those flowers don't harm anyone else's flowers or the long term success of the garden.

Participate in ways that are not directly related to your hardware[edit]

Another tip is to "participate in ways that are not directly related to your hardware." Open source software's quality is dependent on community members improving the software even when it's not immediately in their self-interest. Most contributors tend to already follow this process to some extent. For example, following coding conventions and placing source files into the proper folder isn't always the easiest choice for the individual. In fact, in some cases, following these conventions can make it more difficult to complete your particular task. Nonetheless, by following community conventions, you place the needs of the community above your own. While this is the bare minimum for your code to be accepted, it is not sufficient to getting your hardware support quickly included.

As mentioned previously, open source developers have limited time to focus on all parts of the project. If the folks who are reviewing your change are bogged down with activities that could be handled by others, your code will take longer to be accepted. You can help reduce this delay by participating in ways other than just submitting and supporting your drivers. You could help review patches, write documentation, create tests, answer user questions and maintain servers. The more of this important work you can take on, the faster the community grows and the more efficient it runs.

Let's consider Daniel's metaphor of a community flower garden in the previous section. Let's say the community garden needs new wheelchair accessible walking paths to get between the various plots and the garden entrances. Do you strictly have to help put in these paths? Absolutely not. Helping put in these paths though will spark community growth as new groups of people can plant flowers. While this seems altruistic, and in some cases it can be, there are self-interested reasons for helping out.

When you put in paths to make your garden more accessible, you build your influence in the garden as a whole. New community members might plant flowers which are new to you and you might learn new ways of planting and growing flowers from these new community members. In the case of open source, these new community members might be adding new features or improving existing features in ways you hadn't considered. Additionally, you'll gain credibility and influence in the community. Each of these results will have an actual financial benefit to your employer.

Design patches with upstream Linux in mind[edit]

Lastly, it's important to remember to "design patches with upstream Linux in mind." Submitting a driver that functions in OpenWrt does not guarantee it will be accepted. In fact, functional drivers submitted to OpenWrt may be rejected if they aren't intended to be included in the Linux kernel. At first this may not make sense but OpenWrt has good reasons for this. This policy of avoid final responsibility for driver maintenance is due to the relative size and focus of OpenWrt versus the Linux kernel.

The Linux kernel is supported by dozens if not hundreds of active developers. Each of these developers is reviewing changes that may affect the parts of the kernel they're most interested in. Every change goes through in-depth inspection and must meet a high bar for quality particularly when it relates to hardware compatibility. Long term stability of the low level features of the kernel is ensured due to the maxim: "given enough eyeballs, all bugs are shallow."

On the other hand, OpenWrt is not focused solely on the kernel but also a set of software for building images as well as tools for supporting and maintaining these images. Along with having a broader focus, the core OpenWrt team is far smaller than the kernel team. The OpenWrt community cares very much about long-term stability but without the same size of community and resources, they can't provide the kind of support that the Linux kernel community provides. When combining these two factors, it becomes clear that OpenWrt cannot be the primary maintainers of drivers and the proper place for that maintenance is on the kernel team.

If you want your drivers included in OpenWrt, you should submit your patches to the Linux kernel team. Once accepted, they will get into OpenWrt. That said, the OpenWrt community understands that this schedule might be too long for some hardware manufacturers. In that case, the hardware manufacturer should submit their patches to the kernel as well as to OpenWrt. The best way to get acceptance of a patch in this case is to show that the drivers are being submitted to the kernel and that you will be responsive in maintaining them long term.