[PATCH] nl80211: add notes about userspace API/ABI modifications

[PATCH] nl80211: add notes about userspace API/ABI modifications

[Johannes Berg]

From: Johannes Berg <johannes.berg@intel.com>

Add notes about userspace ABI/API modifications, including the
fact that we decided that API submissions should come with a
driver implementation.

Signed-off-by: Johannes Berg <johannes.berg@intel.com>
---
 include/uapi/linux/nl80211.h | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/include/uapi/linux/nl80211.h b/include/uapi/linux/nl80211.h
index 2dcf9bba317c..74492e85b04f 100644
--- a/include/uapi/linux/nl80211.h
+++ b/include/uapi/linux/nl80211.h
@@ -25,6 +25,19 @@
  *
  */
 
+/*
+ * This header file defines the userspace API to the wireless stack. Please
+ * be careful not to break things - i.e. don't move anything around or so
+ * unless you can demonstrate that it breaks neither API nor ABI.
+ *
+ * Additions to the API should be accompanied by actual implementations in
+ * an upstream driver, so that example implementations exist in case there
+ * are ever concerns about the precise semantics of the API or changes are
+ * needed, and to ensure that code for dead (no longer implemented) API
+ * can actually be identified and removed.
+ * Nonetheless, semantics should also be documented carefully in this file.
+ */
+
 #include <linux/types.h>
 
 #define NL80211_GENL_NAME "nl80211"
-- 
2.1.4

Re: [PATCH] nl80211: add notes about userspace API/ABI modifications

[Arend van Spriel]

On 02/27/15 15:32, Johannes Berg wrote:
> From: Johannes Berg<johannes.berg@intel.com>
>
> Add notes about userspace ABI/API modifications, including the
> fact that we decided that API submissions should come with a
> driver implementation.

Should we also consider Cc: to linux-api mailing list or do you think 
nl80211 api has sufficient capable reviewers. There is probably a reason 
for adding these notes now ;-)

Regards,
Arend

> Signed-off-by: Johannes Berg<johannes.berg@intel.com>
> ---
>   include/uapi/linux/nl80211.h | 13 +++++++++++++
>   1 file changed, 13 insertions(+)
>
> diff --git a/include/uapi/linux/nl80211.h b/include/uapi/linux/nl80211.h
> index 2dcf9bba317c..74492e85b04f 100644
> --- a/include/uapi/linux/nl80211.h
> +++ b/include/uapi/linux/nl80211.h
> @@ -25,6 +25,19 @@
>    *
>    */
>
> +/*
> + * This header file defines the userspace API to the wireless stack. Please
> + * be careful not to break things - i.e. don't move anything around or so
> + * unless you can demonstrate that it breaks neither API nor ABI.
> + *
> + * Additions to the API should be accompanied by actual implementations in
> + * an upstream driver, so that example implementations exist in case there
> + * are ever concerns about the precise semantics of the API or changes are
> + * needed, and to ensure that code for dead (no longer implemented) API
> + * can actually be identified and removed.
> + * Nonetheless, semantics should also be documented carefully in this file.
> + */
> +
>   #include<linux/types.h>
>
>   #define NL80211_GENL_NAME "nl80211"

Re: [PATCH] nl80211: add notes about userspace API/ABI modifications

[Johannes Berg]

On Fri, 2015-02-27 at 17:52 +0100, Arend van Spriel wrote:
> On 02/27/15 15:32, Johannes Berg wrote:
> > From: Johannes Berg<johannes.berg@intel.com>
> >
> > Add notes about userspace ABI/API modifications, including the
> > fact that we decided that API submissions should come with a
> > driver implementation.
> 
> Should we also consider Cc: to linux-api mailing list or do you think 
> nl80211 api has sufficient capable reviewers.

Well, I don't know for sure, but I'd rather not overload the people
there ... there are very few there anyway. And probably most people have
no idea what wifi is ;-)

> There is probably a reason 
> for adding these notes now ;-)

Well, that's mostly the discussion on "need to have an upstream user"

johannes