ethtool development

Contact addresses

Maintainer

Michal Kubecek <mkubecek@suse.cz>

Mailing list

netdev@vger.kernel.org

Repository

The main git repository is git://git.kernel.org/pub/scm/network/ethtool/ethtool.git (gitweb view).

Versions of ethtool follow kernel versions and userspace implementation of new features in kernel ethtool interface should preferrably land in matching ethtool release. However, new ethtool versions must work with older kernels and vice versa, to the maximum possible extent, i.e. all features supported by both kernel and ethtool should work properly.

Similar to kernel networking, there are two target branches: master (for code targeting the closest release) and next (for code to be merged after the closest release). Unlike in kernel, there is no "bugs only" policy for master branch, new features can be also submitted against master with exception of (1) features relying on kernel counterpart not going to be present in the corresponding kernel release (ususally present in kernel net-next tree) and (2) bigger and/or intrusive changes shortly before a release. Those should be submitted against next branch.

User interface

The ethtool user interface leaves something to be desired. In particular, it is currently restricted to the English language. I would appreciate patches to support translation. The output for the "C" locale must not be changed, as there are undoubtedly many scripts that grep the output and depend on the current text.

The ethtool utility is intended for use by system administrators and network administrators, and not primarily by kernel developers. It should not expose unpleasant details of the ethtool API to the user if this can be avoided. For example, the user should not need to know the unfortunate history of and subtle differences between the RX n-tuple versus RX NFC commands. If the user runs ethtool -U with a filter specification that can be represented through either ETHTOOL_SRXNTUPLE or ETHTOOL_RXCLSRLINS, we will try both commands in turn.

Many existing options return exit codes indicating specific failure points. This is not sustainable, as exit codes are 8-bit and shells assign special meaning to values from 127 upward. Any new failure points must produce an exit code of 1.

All new features must be documented in the manual page (ethtool.8.in), and usually in the help text for the relevant option(s).

Coding style

Coding style is broadly similar to the kernel. You can use scripts/checkpatch.pl from the kernel to find style errors before I complain about them!

Submitting patches

Please follow the same procedure as for the kernel, including the Developer's Certificate of Origin. The relevant maintainer and mailing list addresses are shown above. Please use "[PATCH ethtool]" subject prefix in patches or series submitted against main branch and "[PATCH ethtool-next]" in patches or series submitted against next branch.

The build must succeed after every commit, both with netlink interface enabled and disabled (configure --disable-netlink). Submitted series also should not introduce new build warnings. Note: gcc only shows some warnings with optimization enabled so run the build with "-O2" or similar to check for compiler warnings.

If you need new or updated definitions from the kernel userspace API (uapi) headers, run make headers_install in the kernel tree and copy the resulting files into uapi directory. Update all uapi header copies to the same kernel tree snapshot (mainline or net-next tree) and identify this snapshot (by tag or commit id) in your commit message. Commit this change before your other changes. This can be automated using the ethtool-import-uapi script present in the scripts subdirectory of the git repository; it expects LINUX_GIT environment variable to be set to the location of a local copy of kernel git repository, use a commit id, tag or branch name as an argument.

Documentation and code must be kept synchronised, i.e. when you add or change a feature you must update the help text and manual page in the same patch series.