Write a device driver for Zephyr - Part 4
This is the forth post in this series. See also part part1, part2 and part3.
Overview
This is the forth and last part of this series where we will focus on contribute the driver back to the Zephyr project.
Zephyr use Github for hosting the project and all contribution is by Pull Requests. The process is all well documented [1], both on how to contribute but also what the project expect from you as a contributor.
I'm not really a fan of Github. I prefer to send patches by mail and handle all communication that way, but I probably have to realize soon that I'm just getting old and grumpy (needless to say that I prefer IRC over all other chat systems for instant messaging?).
Split up the changes
As we touch multiple areas of the project, we have to break up the changes into multiple commits. This pull request will contain three commits:
Author: Marcus Folkesson <marcus.folkesson@gmail.com>
Date: Wed Apr 5 14:21:47 2023 +0200
dts: bindings: dac: add bindings for ltc1660/ltc1665
Add bindings for LTC1665/LTC1660, which is a 8/10-bit
Digital-to-Analog Converter with eight individual channels.
Signed-off-by: Marcus Folkesson <marcus.folkesson@gmail.com>
commit 6dec8308528a6a5fdf123a8bc24e75ba3e0e8cbd
Author: Marcus Folkesson <marcus.folkesson@gmail.com>
Date: Wed Apr 5 14:18:00 2023 +0200
tests: build_all: add entries for ltc1660/ltc1665
Add the new DAC-drivers to the test suite.
Signed-off-by: Marcus Folkesson <marcus.folkesson@gmail.com>
commit b66b7aade39b79fb3d6194be1b6414491f57a828
Author: Marcus Folkesson <marcus.folkesson@gmail.com>
Date: Wed Apr 5 14:16:13 2023 +0200
drivers: dac: add support for ltc1660/ltc1665
LTC1665/LTC1660 is a 8/10-bit Digital-to-Analog Converter
(DAC) with eight individual channels.
Signed-off-by: Marcus Folkesson <marcus.folkesson@gmail.com>
One miss I see right now as I'm writing this blog post is the commit order. The device tree bindings and the test suite should swap order as the test depends on the bindings.
However, the PR is already merged.
Requirements on the PR
The Zephyr project has several requirements on each pull request, these are:
- Each commit in the PR must provide a commit message following the Commit Message Guidelines.
- All files in the PR must comply with Licensing Requirements.
- Follow the Zephyr Coding Style and Coding Guidelines.
- PRs must pass all CI checks. This is a requirement to merge the PR. Contributors may mark a PR as draft and explicitly request reviewers to provide early feedback, even with failing CI checks.
- When breaking a PR into multiple commits, each commit must build cleanly. The CI system does not enforce this policy, so it's the PR author’s responsibility to verify.
- When major new functionality is added, tests for the new functionality shall be added to the automated test suite. All API functions should have test cases and there should be tests for the behavior contracts of the API. Maintainers and reviewers have the discretion to determine if the provided tests are sufficient. The examples below demonstrate best practices on how to test APIs effectively.
- Kernel timer tests provide around 85% test coverage for the kernel timer , measured by lines of code.
- Emulators for off-chip peripherals are an effective way to test driver APIs. The fuel gauge tests use the smart battery emulator , providing test coverage for the fuel gauge API and the smart battery driver .
- Code coverage reports for the Zephyr project are available on Codecov.
- Incompatible changes to APIs must also update the release notes for the next release detailing the change. APIs marked as experimental are excluded from this requirement.
- Changes to APIs must increment the API version number according to the API version rules.
- PRs must also satisfy all Merge Criteria before a member of the release engineering team merges the PR into the zephyr tree.
This may look overwelming for some, but lets break down some of the requirements.
Commit message Guidelines
All commits should have the following format:
[area]: [summary of change] [Commit message body (must be non-empty)] Signed-off-by: [Your Full Name] <[your.email@address]>
This is more of a common sense rather than something specific for the Zephyr project.
The Signed-off-by: tag should be used for open source licensing reasons. By adding the tag you agree to the Developer Certificate of Origin (DCO) [3]:
Developer's Certificate of Origin 1.1
By making a contribution to this project, I certify that:
- The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or
- The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I'm permitted to submit under a different license), as Indicated in the file; or
- The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it.
- I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved.
License requirements
Zephyr uses the Apache 2.0 license [4] which is a permissive open source license that allows you to freely use, modify, distribute and sell your own produduct that include Apache 2.0 licensed software.
The license is specified by a SPDX tag in the header of each source file. E.g.:
/* * Copyright (c) 2020 Libre Solar Technologies GmbH * * SPDX-License-Identifier: Apache-2.0 */
Final words
My initial thought with this blog series was to give Zephyr another chance since my evaluation didn't go well the first time.
Many people and organizations do use open source for several (good) reasons, but too few actually contribute back to the projects they make use of. Sometimes it's the company culture that doesn't encourage or see the value in it, but mostly it's just a matter of insecurity on the part of the individual developer.
Therefore, this series changed the focus from purely evaluating Zephyr to instead focusing on all the steps I took to get my code into a project I'm quite unfamiliar with. I even changed the blog subject from "First look into Zephyr" to "Write a device driver for Zephyr".
Hopefully it helps someone see that it's not impossible to actually join in and contribute.
References
| [1] | https://docs.zephyrproject.org/latest/contribute/index.html |
| [2] | https://github.com/zephyrproject-rtos/zephyr/pull/56704 |
| [3] | https://docs.zephyrproject.org/latest/contribute/guidelines.html#dco |
| [4] | https://docs.zephyrproject.org/latest/contribute/guidelines.html#licensing-requirements |
| [5] | https://docs.zephyrproject.org/latest/contribute/coding_guidelines/index.html#coding-guidelines |