NOTE: this page is for archival only, see the note at the end of the page.

About this guide

This guide is designed to give you an idea of how to write linux-wireless patches.

Subscribe to this page

We would like to ask Linux-wireless developers to subscribe to this page on the wiki. Any new policies and best practices on patching to linux-wireless will be posted here.

Prior to sending patches

Please DO NOT PGP sign patches sent to linux-wireless. The reason is that signing patches will normalize the and use qp-encoding (Quoated Printable) for the patch. Quoted-Printable encoding replaces characters you can't have in 7-bit by =XX where XX is the hex code. As you can imagine applying such patches will simply not work. Also, please note that we prefer patches inline rather than attachments.

Who to address

If you intend on getting your patch committed address your e-mail as follows:

To: ''John Linville''
CC: ''linux-wireless'', Driver Maintainers, Other Developers

Where Driver Maintainers contains the list of maintianers for the driver you are patching. Other Developers in this case can be a list of developers who you think may like to review this patch.

Subject name

If what you are sending is a patch you can use a subject as follows:

[PATCH] driver_name: fix foo and optimize bar

If your patch is just a proposal you can use this format for your subject:

[RFC][PATCH] driver_name: a new way to do foo

Sending large patches or multiple patches

You should only send a large patch if your patch does one specific task, or a few of them if they are easy to review. If your work consists of multiple tasks you must split your tasks into separate patches. Each patch must address a small set of tasks to help the maintainers with revision. The rule of thumb here is if you read your patch and if its not clear what the patch is doing then better break it down into separate patches. Large patches should also be run through scripts/checkpatch.pl.

If you are sending multiple patches which depend on each other you can use this format for the subjects:

[PATCH 0/4] driver_name: introduce foo and bar
[PATCH 1/4] driver_name: introduce get_foo_bars()
[PATCH 2/4] driver_name: fix locking on bar_by_foo()
[PATCH 3/4] driver_name: use foo when barring
[PATCH 4/4] driver_name: optimize bar at init time

On the e-mail with subject, "[PATCH 0/4] driver_name: introduce foo and bar", you would give a brief overview of all the changes. No patch should be included in that e-mail.

Format of patches

We prefer patches to be inline-text at the end of the body of the e-mail. You can use git-diff or the like to generate the patch. Additionally note that we prefer to apply patches with -p1. A header as follows is then acceptable:

diff --git a/include/net/mac80211.h b/include/net/mac80211.h
index 9b4b4a2..4832e6a 100644
--- a/include/net/mac80211.h
+++ b/include/net/mac80211.h

Footnote on patches

After the stupid SCO incident (which they lost BTW) we figured it'd be best to add new policies to help keep track of provenance of patches. This also helps developers review who was in the line of a patch work, who submitted it, and who reviewed it. This information is available from the git-log. We currently use, Signed-off-by, Acked-by and Cc. It has been proposed to add a new Reviewed-by and even a Tested-by.

Please note that since you are submitting patches inline, after the Signed-off-by: lines, you must put ---, that is three dashes. Example:

...
Signed-off-by: Luis R. Rodriguez <mcgrof@example.com>
---
 include/net/ieee80211_regdomains.h |  196 ++++++++
...

Signed-off-by, Acked-by, Reviewed-by, Tested-by

Quoting Andrew Morton:

  • the Signed-off-by: tag implies that the signer was involved in the development of the patch, or that he/she was in the patch's delivery path. If a person was not directly involved in the preparation or handling of a patch but wishes to signify and record their approval of it then they can arrange to have an Acked-by: line added to the patch's changelog.From Kerneltrap, on '''Linux: Using Acked-by Tags'''

As a patch submitter, the Signed-off-by: can be put right before the patch and diffstat (diffstat is optional). After the Signed-off-by: you must put ---. Reviewed-by tags are something new and it was proposed as many developers were using Acked-by to simply indicate they agree with a patch but not necessarily that they did an actual review of the code involved. You can use Reviewed-by if you want to make clear you actually did do a good amount of review, however Acked-by can be used as that is what its purpose was after all.

Tested-by can be used to indicate additional testers of the patch. If you are submitting a patch, that is – if you are Signing-off on a patch as an author – you should test it. Obviously you can't test all the patches you send, if you haven't tested it then you must specify it in the e-mail.

Changes-licensed-under tag

Based on the new guidelines posted by the SFLC on ''Maintaining Permissive-Licensed Files in a GPL-Licensed Project: Guidelines for Developers'', specifically section 5, we are introducing a new tag for use with patches which deal with files licensed under permissive licenses (BSD, ISC) on the ath5k driver in our larger GPL project, the Linux kernel. The tag is Changes-licensed-under and can be used by developers to clarify the intended license for their patch on permissive licensed files. It is clear that not all changes qualify a patch author for Copyright but a lot of patches do qualify an author for copyright. If you want crystal clear details of what constitutes as a copyrightable change, at least within the US and the EU, you can refer to SFLC's ''Originality Requirements under U.S. and E.U. Copyright Law''.

Although some developers have a practice of implying their patches for a permissive licensed file abides by the respective permissive license of the file being patched, and although some changes are obviously not copyrightable, we would like to ''err on the side of caution'', take the advice from SFLC, and introduce Changes-licensed-under in order to help the BSD family reap benefits of our contributions to permissive licensed files.

The Changes-licensed-under tag should be put before the Signed-off-by tag. Since this tag is used to cover changes under permissive licenses example of possible licenses are 3-Clause-BSD, and ISC. If you are making changes to multiple permissive licensed files then please specify which license covers what files.

Simple example usage of Changes-licensed-under tag, where only one permissive license is used:

[PATCH] ath5k: Internalize Atheros Turbo modes

This patch:

* Internalizes Atheros Turbo modes (MODE_ATHEROS_TURBO,
MODE_ATHEROS_TURBOG)

* Internatizes Turbo modulation (MODULATION_TURBO)

* Adds documention for Atheros Turbo modes (MODE_ATHEROS_TURBO,
MODE_ATHEROS_TURBOG), Turbo modulation (MODULATION_TURBO) and XR
modulation (MODULATION_XR)

Changes-licensed-under: 3-clause-BSD
Signed-off-by: Luis R. Rodriguez <mcgrof@example.com>
Signed-off-by: John W. Linville <linville@example.com
---
diff --git a/drivers/net/wireless/ath5k.h b/drivers/net/wireless/ath5k.h
index 78d7cb2..f6108a8 100644
--- a/drivers/net/wireless/ath5k.h
+++ b/drivers/net/wireless/ath5k.h
@@ -187,12 +187,72 @@ struct ath5k_srev_name {
ETC

Here is an example of a patch head which involves multiple and different permissive licensed files:

[PATCH] ath5k - Fix filters for AR5212, correct return values for WEP

In summary this patch has these changes:

* AR5212 now receives broadcasts (DHCP works now)
* ath5k_hw_set_key() was checking against key table size against
key->keyid -- this can only be 0, 1, 2 or 3. Check against key->keylen
and divide the table size by 8.
* return proper values for WEP setting as per mac80211 documenation

This patch applies to the ath5k branch of wireless-dev.

Changes to ath5k_base.c
Changes-licensed-under: 3-clause-BSD

Changes to ath5k_hw.c, ath5k_reg.h
Changes-licensed-under: ISC

Signed-off-by: Luis R. Rodriguez <mcgrof@example.com>

---

 drivers/net/wireless/ath5k_base.c |   26 ++++++++++++++++++--------
 1 files changed, 18 insertions(+), 8 deletions(-

 drivers/net/wireless/ath5k_hw.c  |   12 +++++++++---
 drivers/net/wireless/ath5k_reg.h |   12 ++++++++++++
 2 files changed, 21 insertions(+), 3 deletions(-)

ETC

Examples of a patches

Below are a few examples of a patches. Only the header is provided for long patches.

  • Single patch

From: Michael Buesch
To: John Linville
Cc: linux-wireless, Bcm43xx-dev, Larry Finger
Subject: [PATCH] b43: Remove the "radio hw enabled" message on startup.

This message is useless. Only report state changes.

Signed-off-by: Michael Buesch <mb@example.com>
Cc: Larry Finger <larry.finger@example.com>

---

Index: wireless-dev/drivers/net/wireless/b43/main.c
===================================================================
--- wireless-dev.orig/drivers/net/wireless/b43/main.c   2007-09-20 19:39:06.000000000 +0200
+++ wireless-dev/drivers/net/wireless/b43/main.c        2007-09-20 20:06:24.000000000 +0200
@@ -2227,9 +2227,6 @@ static int b43_chip_init(struct b43_wlde
       if (err)
               goto err_gpio_cleanup;
       b43_radio_turn_on(dev);
-       dev->radio_hw_enable = b43_is_hw_radio_enabled(dev);
-       b43dbg(dev->wl, "Radio %s by hardware\n",
-              dev->radio_hw_enable ? "enabled" : "disabled");

       b43_write16(dev, 0x03E6, 0x0000);
       err = b43_phy_init(dev);
@@ -3251,6 +3248,9 @@ static void setup_struct_wldev_for_init(
 {
       /* Flags */
       dev->reg124_set_0x4 = 0;
+       /* Assume the radio is enabled. If it's not enabled, the state will
+        * immediately get fixed on the first periodic work run. */
+       dev->radio_hw_enable = 1;

       /* Stats */
       memset(&dev->stats, 0, sizeof(dev->stats));
-
  • Multiple patches

From: Luis R. Rodriguez
To: John Linville
Cc: linux-wireless, Michael Wu, Johannes Berg, Daniel Drake, Larry Finger
Subject: [PATCH 3/5] Wireless: add IEEE-802.11 regualtory domain module

This adds the regulatory domain module. It provides a way to
allocate and construct a regulatory domain based on the current
map. This module provides no enforcement, it just does the actual
building of the regdomain and returns it as defined in ieee80211_regdomains.h

This module depends on the ISO3166-1 module.

Signed-off-by: Luis R. Rodriguez <mcgrof@example.com>

---
 include/net/ieee80211_regdomains.h |  196 ++++++++
 net/wireless/Kconfig               |   16 +
 net/wireless/Makefile              |    1 +
 net/wireless/reg_common.h          |  138 ++++++
 net/wireless/regdomains.c          |  751 ++++++++++++++++++++++++++++++
 net/wireless/regulatory_map.h      |  887 ++++++++++++++++++++++++++++++++++++
 6 files changed, 1989 insertions(+), 0 deletions(-)
 create mode 100644 include/net/ieee80211_regdomains.h
 create mode 100644 net/wireless/reg_common.h
 create mode 100644 net/wireless/regdomains.c
 create mode 100644 net/wireless/regulatory_map.h

diff --git a/include/net/ieee80211_regdomains.h b/include/net/ieee80211_regdomains.h
new file mode 100644
index 0000000..adf4de4
--- /dev/null
+++ b/include/net/ieee80211_regdomains.h
@@ -0,0 +1,196 @@
+#ifndef _IEEE80211_REGDOMAIN_H
+#define _IEEE80211_REGDOMAIN_H
+/*
... ETC ...

More patch work references

Here is a list of links to help you write better patches


This is a static dump of the wiki, taken after locking it in January 2015. The new wiki is at https://wireless.wiki.kernel.org/.
versions of this page: last, v25, v24, v23, v22, v21, v20, v19, v18, v17, v16, v15, v14, v13, v12, v11, v10, v9, v8, v7, v6, v5, v4, v3, v2, v1