[PATCH trivial] UAPI: Kbuild: add/modify comments for "uapi/Kbuild" and "uapi/linux/Kbuild"

[PATCH trivial] UAPI: Kbuild: add/modify comments for "uapi/Kbuild" and "uapi/linux/Kbuild"

[Chen Gang]

"include/uapi/" is the whole Linux kernel API, it is important enough
to get more global explanations by comments.

In "include/uapi/Kbuild", "Makefile..." and "non-arch..." comments are
meaningless for current 'Kbuild', so delete them.

And add more explanations for "include/uapi/" in "include/uapi/Kbuild",
also add more explanations for "include/uapi/linux/" in "include/uapi
/linux/Kbuild".


Signed-off-by: Chen Gang <gang.chen@asianux.com>
---
 include/uapi/Kbuild       |    5 ++---
 include/uapi/linux/Kbuild |    2 ++
 2 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/include/uapi/Kbuild b/include/uapi/Kbuild
index 81d2106..c682891 100644
--- a/include/uapi/Kbuild
+++ b/include/uapi/Kbuild
@@ -1,7 +1,6 @@
 # UAPI Header export list
-# Top-level Makefile calls into asm-$(ARCH)
-# List only non-arch directories below
-
+# Except "linux/", UAPI means Universal API.
+# For "linux/", UAPI means User API which can be used by user mode.
 
 header-y += asm-generic/
 header-y += linux/
diff --git a/include/uapi/linux/Kbuild b/include/uapi/linux/Kbuild
index 997f9f2..0025e07 100644
--- a/include/uapi/linux/Kbuild
+++ b/include/uapi/linux/Kbuild
@@ -1,4 +1,6 @@
 # UAPI Header export list
+# UAPI is User API which can be used by user mode.
+
 header-y += byteorder/
 header-y += can/
 header-y += caif/
-- 
1.7.7.6

Re: [PATCH trivial] UAPI: Kbuild: add/modify comments for "uapi/Kbuild" and "uapi/linux/Kbuild"

[Joe Perches]

On Tue, 2013-08-06 at 09:46 +0800, Chen Gang wrote:
> "include/uapi/" is the whole Linux kernel API, it is important enough
> to get more global explanations by comments.

It'd probably be useful to have more descriptions
of uapi in the Documentation directory too.

Re: [PATCH trivial] UAPI: Kbuild: add/modify comments for "uapi/Kbuild" and "uapi/linux/Kbuild"

[Chen Gang]

On 08/07/2013 01:31 AM, Joe Perches wrote:
> On Tue, 2013-08-06 at 09:46 +0800, Chen Gang wrote:
>> "include/uapi/" is the whole Linux kernel API, it is important enough
>> to get more global explanations by comments.
> 
> It'd probably be useful to have more descriptions
> of uapi in the Documentation directory too.
> 

Yeah, at least, I also think so.

Since it is an 'important' document, I recommend to let it written by an
'important' member, and be discussed or checked by all related members.

But for what I did (this patch) is mainly for the summary comments. So I
think it is enough to be discussed and checked by the members which
"./scripts/get_maintainers.pl" suggests.


Thanks.
-- 
Chen Gang

Re: [PATCH trivial] UAPI: Kbuild: add/modify comments for "uapi/Kbuild" and "uapi/linux/Kbuild"

[Rob Landley]

On 08/06/2013 12:31:43 PM, Joe Perches wrote:
> On Tue, 2013-08-06 at 09:46 +0800, Chen Gang wrote:
> > "include/uapi/" is the whole Linux kernel API, it is important  
> enough
> > to get more global explanations by comments.
> 
> It'd probably be useful to have more descriptions
> of uapi in the Documentation directory too.

I'd rather have comments in the headers that get exported to userspace  
and then have other forms of documentation generated from that by some  
process similar to "make htmldocs". Otherwise you've got two places to  
keep in sync.

(Really the guy you've got to keep in the loop about this is Michael  
Kerrisk. The section 2 man pages are the current best reference on UAPI  
stuff...)

Rob

Re: [PATCH trivial] UAPI: Kbuild: add/modify comments for "uapi/Kbuild" and "uapi/linux/Kbuild"

[Chen Gang]

On 08/07/2013 03:32 PM, Rob Landley wrote:
> On 08/06/2013 12:31:43 PM, Joe Perches wrote:
>> On Tue, 2013-08-06 at 09:46 +0800, Chen Gang wrote:
>> > "include/uapi/" is the whole Linux kernel API, it is important enough
>> > to get more global explanations by comments.
>>
>> It'd probably be useful to have more descriptions
>> of uapi in the Documentation directory too.
> 
> I'd rather have comments in the headers that get exported to userspace
> and then have other forms of documentation generated from that by some
> process similar to "make htmldocs". Otherwise you've got two places to
> keep in sync.
> 

At least for me, it is a good idea, although UAPI files is rarely
changed (may add new item, but few modifying the existing items).

And for our case, it is summary comments for directory organization for
all UAPI files, so in my opinion, it is still necessary to give summary
comments in Kbuild.

In Linux user mode or another OS which share the same files of UAPI,
they do not care about our kernel's Kbuild, for they have their own
directory organizations which may different with Linux kernel's.

> (Really the guy you've got to keep in the loop about this is Michael
> Kerrisk. The section 2 man pages are the current best reference on UAPI
> stuff...)
> 

As far as I know, the section 2 man pages is already for it (e.g. man 2
setfuid, man 2 open, ...).

Do you mean currently it is only for some of system calls (part of
UAPI), not for the whole UAPI ?


> Rob
> 


-- 
Chen Gang

Re: [PATCH trivial] UAPI: Kbuild: add/modify comments for "uapi/Kbuild" and "uapi/linux/Kbuild"

[Chen Gang]

Hello Rob:

Maybe I misunderstand what you said (if so, I am sorry for it).

At least for me, what you said is valuable to get additional discussion,
but it seems better to start a new thread for it and also cc to
linux-doc mail list.

If so better include me in cc list, thanks.  ;-)

If you think still suitable to discuss about it in this mail thread,
please continue, at least, I still welcome.  :-)


Thanks.

On 08/07/2013 04:48 PM, Chen Gang wrote:
> On 08/07/2013 03:32 PM, Rob Landley wrote:
>> On 08/06/2013 12:31:43 PM, Joe Perches wrote:
>>> On Tue, 2013-08-06 at 09:46 +0800, Chen Gang wrote:
>>>> "include/uapi/" is the whole Linux kernel API, it is important enough
>>>> to get more global explanations by comments.
>>>
>>> It'd probably be useful to have more descriptions
>>> of uapi in the Documentation directory too.
>>
>> I'd rather have comments in the headers that get exported to userspace
>> and then have other forms of documentation generated from that by some
>> process similar to "make htmldocs". Otherwise you've got two places to
>> keep in sync.
>>
> 
> At least for me, it is a good idea, although UAPI files is rarely
> changed (may add new item, but few modifying the existing items).
> 
> And for our case, it is summary comments for directory organization for
> all UAPI files, so in my opinion, it is still necessary to give summary
> comments in Kbuild.
> 
> In Linux user mode or another OS which share the same files of UAPI,
> they do not care about our kernel's Kbuild, for they have their own
> directory organizations which may different with Linux kernel's.
> 
>> (Really the guy you've got to keep in the loop about this is Michael
>> Kerrisk. The section 2 man pages are the current best reference on UAPI
>> stuff...)
>>
> 
> As far as I know, the section 2 man pages is already for it (e.g. man 2
> setfuid, man 2 open, ...).
> 
> Do you mean currently it is only for some of system calls (part of
> UAPI), not for the whole UAPI ?
> 
> 
>> Rob
>>
> 
> 


-- 
Chen Gang

Re: [PATCH trivial] UAPI: Kbuild: add/modify comments for "uapi/Kbuild" and "uapi/linux/Kbuild"

[Chen Gang]

Hello all:

According to the reply of yours, it seems we need more 'work' for the
API related documents.  If really it is, I need change my 'work' way
for it.

Currently, my 'work' way is "finding and solving issues", which may be
efficient for 'grow up' sub-systems (e.g. "kernel/" sub-system).

But for the sub-systems which are lack of main contents (or too many
issues to solve), I think the efficient way is "get 'tasks' from the
related maintainers and finish 'tasks' one by one".

If the related maintainers agree with me, they can send 'tasks' to me,
and I am glad to finish them one by one.


Reason (why I am glad to do it):

  1. The API related documents are really important for us, and currently need more 'work'.
  2. 'getting tasks' is an efficient way for it.
  3. it is additional good chance to me for English training (I should do additional trying to improve my English).


Limitations (my resources):

  1. finish one API document related task per month (excuse me, I have no additional time resources for it).
  2. my English is not quite well, it may have negative effect with the efficiency.
  3. sometimes, I can not connect to net, which may not give response in time.

     e.g. recently, 2013-08-08 -- 2013-08-19, but I may still can 'work' for it (queue patches and waiting the network OK).


BTW: I also can try the English-Chinese translations tasks. ;-)


Thanks.


On 08/08/2013 10:13 AM, Chen Gang wrote:
> Hello Rob:
> 
> Maybe I misunderstand what you said (if so, I am sorry for it).
> 
> At least for me, what you said is valuable to get additional discussion,
> but it seems better to start a new thread for it and also cc to
> linux-doc mail list.
> 
> If so better include me in cc list, thanks.  ;-)
> 
> If you think still suitable to discuss about it in this mail thread,
> please continue, at least, I still welcome.  :-)
> 
> 
> Thanks.
> 
> On 08/07/2013 04:48 PM, Chen Gang wrote:
>> On 08/07/2013 03:32 PM, Rob Landley wrote:
>>> On 08/06/2013 12:31:43 PM, Joe Perches wrote:
>>>> On Tue, 2013-08-06 at 09:46 +0800, Chen Gang wrote:
>>>>> "include/uapi/" is the whole Linux kernel API, it is important enough
>>>>> to get more global explanations by comments.
>>>>
>>>> It'd probably be useful to have more descriptions
>>>> of uapi in the Documentation directory too.
>>>
>>> I'd rather have comments in the headers that get exported to userspace
>>> and then have other forms of documentation generated from that by some
>>> process similar to "make htmldocs". Otherwise you've got two places to
>>> keep in sync.
>>>
>>
>> At least for me, it is a good idea, although UAPI files is rarely
>> changed (may add new item, but few modifying the existing items).
>>
>> And for our case, it is summary comments for directory organization for
>> all UAPI files, so in my opinion, it is still necessary to give summary
>> comments in Kbuild.
>>
>> In Linux user mode or another OS which share the same files of UAPI,
>> they do not care about our kernel's Kbuild, for they have their own
>> directory organizations which may different with Linux kernel's.
>>
>>> (Really the guy you've got to keep in the loop about this is Michael
>>> Kerrisk. The section 2 man pages are the current best reference on UAPI
>>> stuff...)
>>>
>>
>> As far as I know, the section 2 man pages is already for it (e.g. man 2
>> setfuid, man 2 open, ...).
>>
>> Do you mean currently it is only for some of system calls (part of
>> UAPI), not for the whole UAPI ?
>>
>>
>>> Rob
>>>
>>
>>
> 
> 


-- 
Chen Gang

Re: [PATCH trivial] UAPI: Kbuild: add/modify comments for "uapi/Kbuild" and "uapi/linux/Kbuild"

[Chen Gang]

Hello Maintainers:

Is this patch suitable for applying ?  Does it belong to 'trivial' (or
'Documentation', or others) ?


And sorry for my original missing some important mail addresses when I
sent the original patch (I got them by "./scripts/get_maintainers", and
not give more considerations for them).

So I append my original patch below, if necessary, please help check
when you have time, thanks.


------------------------------patch begin-------------------------------

"include/uapi/" is the whole Linux kernel API, it is important enough
to get more global explanations by comments.

In "include/uapi/Kbuild", "Makefile..." and "non-arch..." comments are
meaningless for current 'Kbuild', so delete them.

And add more explanations for "include/uapi/" in "include/uapi/Kbuild",
also add more explanations for "include/uapi/linux/" in "include/uapi
/linux/Kbuild".


Signed-off-by: Chen Gang <gang.chen@asianux.com>
---
 include/uapi/Kbuild       |    5 ++---
 include/uapi/linux/Kbuild |    2 ++
 2 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/include/uapi/Kbuild b/include/uapi/Kbuild
index 81d2106..c682891 100644
--- a/include/uapi/Kbuild
+++ b/include/uapi/Kbuild
@@ -1,7 +1,6 @@
 # UAPI Header export list
-# Top-level Makefile calls into asm-$(ARCH)
-# List only non-arch directories below
-
+# Except "linux/", UAPI means Universal API.
+# For "linux/", UAPI means User API which can be used by user mode.

 header-y += asm-generic/
 header-y += linux/
diff --git a/include/uapi/linux/Kbuild b/include/uapi/linux/Kbuild
index 997f9f2..0025e07 100644
--- a/include/uapi/linux/Kbuild
+++ b/include/uapi/linux/Kbuild
@@ -1,4 +1,6 @@
 # UAPI Header export list
+# UAPI is User API which can be used by user mode.
+
 header-y += byteorder/
 header-y += can/
 header-y += caif/
-- 
1.7.7.6

------------------------------patch end---------------------------------


Thanks.


On 08/21/2013 02:34 PM, Chen Gang wrote:
> Hello all:
> 
> According to the reply of yours, it seems we need more 'work' for the
> API related documents.  If really it is, I need change my 'work' way
> for it.
> 
> Currently, my 'work' way is "finding and solving issues", which may be
> efficient for 'grow up' sub-systems (e.g. "kernel/" sub-system).
> 
> But for the sub-systems which are lack of main contents (or too many
> issues to solve), I think the efficient way is "get 'tasks' from the
> related maintainers and finish 'tasks' one by one".
> 
> If the related maintainers agree with me, they can send 'tasks' to me,
> and I am glad to finish them one by one.
> 
> 
> Reason (why I am glad to do it):
> 
>   1. The API related documents are really important for us, and currently need more 'work'.
>   2. 'getting tasks' is an efficient way for it.
>   3. it is additional good chance to me for English training (I should do additional trying to improve my English).
> 
> 
> Limitations (my resources):
> 
>   1. finish one API document related task per month (excuse me, I have no additional time resources for it).
>   2. my English is not quite well, it may have negative effect with the efficiency.
>   3. sometimes, I can not connect to net, which may not give response in time.
> 
>      e.g. recently, 2013-08-08 -- 2013-08-19, but I may still can 'work' for it (queue patches and waiting the network OK).
> 
> 
> BTW: I also can try the English-Chinese translations tasks. ;-)
> 
> 
> Thanks.
> 
> 
> On 08/08/2013 10:13 AM, Chen Gang wrote:
>> Hello Rob:
>>
>> Maybe I misunderstand what you said (if so, I am sorry for it).
>>
>> At least for me, what you said is valuable to get additional discussion,
>> but it seems better to start a new thread for it and also cc to
>> linux-doc mail list.
>>
>> If so better include me in cc list, thanks.  ;-)
>>
>> If you think still suitable to discuss about it in this mail thread,
>> please continue, at least, I still welcome.  :-)
>>
>>
>> Thanks.
>>
>> On 08/07/2013 04:48 PM, Chen Gang wrote:
>>> On 08/07/2013 03:32 PM, Rob Landley wrote:
>>>> On 08/06/2013 12:31:43 PM, Joe Perches wrote:
>>>>> On Tue, 2013-08-06 at 09:46 +0800, Chen Gang wrote:
>>>>>> "include/uapi/" is the whole Linux kernel API, it is important enough
>>>>>> to get more global explanations by comments.
>>>>>
>>>>> It'd probably be useful to have more descriptions
>>>>> of uapi in the Documentation directory too.
>>>>
>>>> I'd rather have comments in the headers that get exported to userspace
>>>> and then have other forms of documentation generated from that by some
>>>> process similar to "make htmldocs". Otherwise you've got two places to
>>>> keep in sync.
>>>>
>>>
>>> At least for me, it is a good idea, although UAPI files is rarely
>>> changed (may add new item, but few modifying the existing items).
>>>
>>> And for our case, it is summary comments for directory organization for
>>> all UAPI files, so in my opinion, it is still necessary to give summary
>>> comments in Kbuild.
>>>
>>> In Linux user mode or another OS which share the same files of UAPI,
>>> they do not care about our kernel's Kbuild, for they have their own
>>> directory organizations which may different with Linux kernel's.
>>>
>>>> (Really the guy you've got to keep in the loop about this is Michael
>>>> Kerrisk. The section 2 man pages are the current best reference on UAPI
>>>> stuff...)
>>>>
>>>
>>> As far as I know, the section 2 man pages is already for it (e.g. man 2
>>> setfuid, man 2 open, ...).
>>>
>>> Do you mean currently it is only for some of system calls (part of
>>> UAPI), not for the whole UAPI ?
>>>
>>>
>>>> Rob
>>>>
>>>
>>>
>>
>>
> 
> 


-- 
Chen Gang

Re: [PATCH trivial] UAPI: Kbuild: add/modify comments for "uapi/Kbuild" and "uapi/linux/Kbuild"

[Chen Gang]

Hello Maintainers:

Maybe... I still miss some important mail addresses? or this patch is
not suitable for applying?

Hmm... but I still want to try the last time: "please help check this
patch, when you have time".

And next, I should not send additional tracing mail again, that will be
really spam.


Thanks.

On 08/23/2013 06:30 PM, Chen Gang wrote:
> Hello Maintainers:
> 
> Is this patch suitable for applying ?  Does it belong to 'trivial' (or
> 'Documentation', or others) ?
> 
> 
> And sorry for my original missing some important mail addresses when I
> sent the original patch (I got them by "./scripts/get_maintainers", and
> not give more considerations for them).
> 
> So I append my original patch below, if necessary, please help check
> when you have time, thanks.
> 
> 
> ------------------------------patch begin-------------------------------
> 
> "include/uapi/" is the whole Linux kernel API, it is important enough
> to get more global explanations by comments.
> 
> In "include/uapi/Kbuild", "Makefile..." and "non-arch..." comments are
> meaningless for current 'Kbuild', so delete them.
> 
> And add more explanations for "include/uapi/" in "include/uapi/Kbuild",
> also add more explanations for "include/uapi/linux/" in "include/uapi
> /linux/Kbuild".
> 
> 
> Signed-off-by: Chen Gang <gang.chen@asianux.com>
> ---
>  include/uapi/Kbuild       |    5 ++---
>  include/uapi/linux/Kbuild |    2 ++
>  2 files changed, 4 insertions(+), 3 deletions(-)
> 
> diff --git a/include/uapi/Kbuild b/include/uapi/Kbuild
> index 81d2106..c682891 100644
> --- a/include/uapi/Kbuild
> +++ b/include/uapi/Kbuild
> @@ -1,7 +1,6 @@
>  # UAPI Header export list
> -# Top-level Makefile calls into asm-$(ARCH)
> -# List only non-arch directories below
> -
> +# Except "linux/", UAPI means Universal API.
> +# For "linux/", UAPI means User API which can be used by user mode.
> 
>  header-y += asm-generic/
>  header-y += linux/
> diff --git a/include/uapi/linux/Kbuild b/include/uapi/linux/Kbuild
> index 997f9f2..0025e07 100644
> --- a/include/uapi/linux/Kbuild
> +++ b/include/uapi/linux/Kbuild
> @@ -1,4 +1,6 @@
>  # UAPI Header export list
> +# UAPI is User API which can be used by user mode.
> +
>  header-y += byteorder/
>  header-y += can/
>  header-y += caif/
> 


-- 
Chen Gang

[PATCH trivial v2] UAPI: Kbuild: add/modify comments for "uapi/Kbuild" and "uapi/linux/Kbuild"

[Chen Gang]

"include/uapi/" is the whole Linux kernel API, it is important enough
to get more global explanations by comments.

In "include/uapi/Kbuild", "Makefile..." and "non-arch..." comments are
meaningless for current 'Kbuild', so delete them.

And add more explanations for "include/uapi/" in "include/uapi/Kbuild",


Signed-off-by: Chen Gang <gang.chen@asianux.com>
---
 include/uapi/Kbuild |    7 ++++---
 1 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/include/uapi/Kbuild b/include/uapi/Kbuild
index 81d2106..287e8d0 100644
--- a/include/uapi/Kbuild
+++ b/include/uapi/Kbuild
@@ -1,7 +1,8 @@
 # UAPI Header export list
-# Top-level Makefile calls into asm-$(ARCH)
-# List only non-arch directories below
-
+#
+# UAPI means "Userspace API" which will be installed to "/usr/include".
+# Except "linux/", the other current level directories are for compatibility.
+# It will not accept the new additional current level directories or files.
 
 header-y += asm-generic/
 header-y += linux/
-- 
1.7.7.6

Re: [PATCH trivial v2] UAPI: Kbuild: add/modify comments for "uapi/Kbuild" and "uapi/linux/Kbuild"

[Chen Gang]

Oh, sorry the patch subject should be changed too. I will send patch v3.

On 09/05/2013 08:46 AM, Chen Gang wrote:
> "include/uapi/" is the whole Linux kernel API, it is important enough
> to get more global explanations by comments.
> 
> In "include/uapi/Kbuild", "Makefile..." and "non-arch..." comments are
> meaningless for current 'Kbuild', so delete them.
> 
> And add more explanations for "include/uapi/" in "include/uapi/Kbuild",
> 
> 
> Signed-off-by: Chen Gang <gang.chen@asianux.com>
> ---
>  include/uapi/Kbuild |    7 ++++---
>  1 files changed, 4 insertions(+), 3 deletions(-)
> 
> diff --git a/include/uapi/Kbuild b/include/uapi/Kbuild
> index 81d2106..287e8d0 100644
> --- a/include/uapi/Kbuild
> +++ b/include/uapi/Kbuild
> @@ -1,7 +1,8 @@
>  # UAPI Header export list
> -# Top-level Makefile calls into asm-$(ARCH)
> -# List only non-arch directories below
> -
> +#
> +# UAPI means "Userspace API" which will be installed to "/usr/include".
> +# Except "linux/", the other current level directories are for compatibility.
> +# It will not accept the new additional current level directories or files.
>  
>  header-y += asm-generic/
>  header-y += linux/
> 


-- 
Chen Gang

[PATCH trivial v3] include/uapi/Kbuild: modify the comments for it

[Chen Gang]

"include/uapi/" is the whole Linux kernel API, it is important enough
to get more global explanations by comments.

In "include/uapi/Kbuild", "Makefile..." and "non-arch..." comments are
meaningless for current 'Kbuild', so delete them.

And add more explanations for "include/uapi/" in "include/uapi/Kbuild",


Signed-off-by: Chen Gang <gang.chen@asianux.com>
---
 include/uapi/Kbuild |    7 ++++---
 1 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/include/uapi/Kbuild b/include/uapi/Kbuild
index 81d2106..287e8d0 100644
--- a/include/uapi/Kbuild
+++ b/include/uapi/Kbuild
@@ -1,7 +1,8 @@
 # UAPI Header export list
-# Top-level Makefile calls into asm-$(ARCH)
-# List only non-arch directories below
-
+#
+# UAPI means "Userspace API" which will be installed to "/usr/include".
+# Except "linux/", the other current level directories are for compatibility.
+# It will not accept the new additional current level directories or files.
 
 header-y += asm-generic/
 header-y += linux/
-- 
1.7.7.6

Re: [PATCH trivial v3] include/uapi/Kbuild: modify the comments for it

[Chen Gang]

On 09/05/2013 09:09 AM, Chen Gang wrote:
> "include/uapi/" is the whole Linux kernel API, it is important enough
> to get more global explanations by comments.
> 
> In "include/uapi/Kbuild", "Makefile..." and "non-arch..." comments are
> meaningless for current 'Kbuild', so delete them.
> 

Hmm...it is better to improve original comments instead of delete them:
Need give some comments for "arch/*/include/uapi/asm" in
"include/uapi/Kbuild". :-)

> And add more explanations for "include/uapi/" in "include/uapi/Kbuild",
> 

"add more explanations" is still need.


I will send patch v4 for it. :-)

Thanks.

> 
> Signed-off-by: Chen Gang <gang.chen@asianux.com>
> ---
>  include/uapi/Kbuild |    7 ++++---
>  1 files changed, 4 insertions(+), 3 deletions(-)
> 
> diff --git a/include/uapi/Kbuild b/include/uapi/Kbuild
> index 81d2106..287e8d0 100644
> --- a/include/uapi/Kbuild
> +++ b/include/uapi/Kbuild
> @@ -1,7 +1,8 @@
>  # UAPI Header export list
> -# Top-level Makefile calls into asm-$(ARCH)
> -# List only non-arch directories below
> -
> +#
> +# UAPI means "Userspace API" which will be installed to "/usr/include".
> +# Except "linux/", the other current level directories are for compatibility.
> +# It will not accept the new additional current level directories or files.
>  
>  header-y += asm-generic/
>  header-y += linux/
> 


-- 
Chen Gang

[PATCH trivial v4] include/uapi/Kbuild: modify comment to provide summary descriptions for Linux UAPI

[Chen Gang]

UAPI is whole Linux kernel API, it is important enough to get summary
descriptions by comments.

In "include/uapi/Kbuild", "Makefile..." and "non-arch..." comments are
historical, at present, they need be improved.

Also add more explanations for "include/uapi/" in "include/uapi/Kbuild".


Signed-off-by: Chen Gang <gang.chen@asianux.com>
---
 include/uapi/Kbuild |   13 +++++++++++--
 1 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/include/uapi/Kbuild b/include/uapi/Kbuild
index 81d2106..f396115 100644
--- a/include/uapi/Kbuild
+++ b/include/uapi/Kbuild
@@ -1,6 +1,15 @@
 # UAPI Header export list
-# Top-level Makefile calls into asm-$(ARCH)
-# List only non-arch directories below
+#
+# UAPI ("Userspace API") is in "include/uapi/" and "arch/*/include/uapi/",
+# which will be installed to "/usr/include".
+#
+# Linux generic (architecture independent) UAPI is at "include/uapi/".
+# Except "linux/", other current level sub-directories are for compatibility.
+# It will not accept new additional current level sub-directories or files.
+#
+# "Architecture Specific Mechanism" UAPI is at "arch/*/include/uapi/".
+# Each architecture must have "arch/*/include/uapi/asm" sub-directory.
+# If architecture permits, it can content additional sub-directories.
 
 
 header-y += asm-generic/
-- 
1.7.7.6

Re: [PATCH trivial] UAPI: Kbuild: add/modify comments for "uapi/Kbuild" and "uapi/linux/Kbuild"

[Geert Uytterhoeven]

On Tue, Aug 6, 2013 at 3:46 AM, Chen Gang <gang.chen@asianux.com> wrote:
> --- a/include/uapi/Kbuild
> +++ b/include/uapi/Kbuild
> @@ -1,7 +1,6 @@
>  # UAPI Header export list
> -# Top-level Makefile calls into asm-$(ARCH)
> -# List only non-arch directories below
> -
> +# Except "linux/", UAPI means Universal API.

Sorry for my silly question, but what's the purpose of this "Universal
API" comment?

> +# For "linux/", UAPI means User API which can be used by user mode.
>
>  header-y += asm-generic/
>  header-y += linux/

Gr{oetje,eeting}s,

                        Geert

--
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert@linux-m68k.org

In personal conversations with technical people, I call myself a hacker. But
when I'm talking to journalists I just say "programmer" or something like that.
                                -- Linus Torvalds

Re: [PATCH trivial] UAPI: Kbuild: add/modify comments for "uapi/Kbuild" and "uapi/linux/Kbuild"

[Chen Gang]

On 09/04/2013 12:41 AM, Geert Uytterhoeven wrote:
> On Tue, Aug 6, 2013 at 3:46 AM, Chen Gang <gang.chen@asianux.com> wrote:
>> --- a/include/uapi/Kbuild
>> +++ b/include/uapi/Kbuild
>> @@ -1,7 +1,6 @@
>>  # UAPI Header export list
>> -# Top-level Makefile calls into asm-$(ARCH)
>> -# List only non-arch directories below
>> -
>> +# Except "linux/", UAPI means Universal API.
> 
> Sorry for my silly question, but what's the purpose of this "Universal
> API" comment?
> 

Firstly, at least for me, I don't think it is a silly question (maybe
it means I should give additional explanations).  :-)

I 'guess' the "Universal API" means:

  "the API which can be used under multiple OS (independent from Linux), it may be used under kernel mode or user mode".

It is just my 'guess', welcome additional suggestions or completions by
any members.

When we get this correct additional explanation after discussing, if
suitable, I should add the final explanation to current patch.


Thanks.

>> +# For "linux/", UAPI means User API which can be used by user mode.
>>
>>  header-y += asm-generic/
>>  header-y += linux/
> 
> Gr{oetje,eeting}s,
> 
>                         Geert
> 
> --
> Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert@linux-m68k.org
> 
> In personal conversations with technical people, I call myself a hacker. But
> when I'm talking to journalists I just say "programmer" or something like that.
>                                 -- Linus Torvalds
> 
> 


-- 
Chen Gang

Re: [PATCH trivial] UAPI: Kbuild: add/modify comments for "uapi/Kbuild" and "uapi/linux/Kbuild"

[Geert Uytterhoeven]

On Wed, Sep 4, 2013 at 3:08 AM, Chen Gang <gang.chen@asianux.com> wrote:
> On 09/04/2013 12:41 AM, Geert Uytterhoeven wrote:
>> On Tue, Aug 6, 2013 at 3:46 AM, Chen Gang <gang.chen@asianux.com> wrote:
>>> --- a/include/uapi/Kbuild
>>> +++ b/include/uapi/Kbuild
>>> @@ -1,7 +1,6 @@
>>>  # UAPI Header export list
>>> -# Top-level Makefile calls into asm-$(ARCH)
>>> -# List only non-arch directories below
>>> -
>>> +# Except "linux/", UAPI means Universal API.
>>
>> Sorry for my silly question, but what's the purpose of this "Universal
>> API" comment?
>>
>
> Firstly, at least for me, I don't think it is a silly question (maybe
> it means I should give additional explanations).  :-)
>
> I 'guess' the "Universal API" means:
>
>   "the API which can be used under multiple OS (independent from Linux), it may be used under kernel mode or user mode".
>
> It is just my 'guess', welcome additional suggestions or completions by
> any members.
>
> When we get this correct additional explanation after discussing, if
> suitable, I should add the final explanation to current patch.

Thanks. As this is not related at all to Linux, I don't see a reason
to add this comment.

Here, "UAPI" means "userspace API" only.

Gr{oetje,eeting}s,

                        Geert

--
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert@linux-m68k.org

In personal conversations with technical people, I call myself a hacker. But
when I'm talking to journalists I just say "programmer" or something like that.
                                -- Linus Torvalds

Re: [PATCH trivial] UAPI: Kbuild: add/modify comments for "uapi/Kbuild" and "uapi/linux/Kbuild"

[Chen Gang]

On 09/04/2013 03:02 PM, Geert Uytterhoeven wrote:
> On Wed, Sep 4, 2013 at 3:08 AM, Chen Gang <gang.chen@asianux.com> wrote:
>> On 09/04/2013 12:41 AM, Geert Uytterhoeven wrote:
>>> On Tue, Aug 6, 2013 at 3:46 AM, Chen Gang <gang.chen@asianux.com> wrote:
>>>> --- a/include/uapi/Kbuild
>>>> +++ b/include/uapi/Kbuild
>>>> @@ -1,7 +1,6 @@
>>>>  # UAPI Header export list
>>>> -# Top-level Makefile calls into asm-$(ARCH)
>>>> -# List only non-arch directories below
>>>> -
>>>> +# Except "linux/", UAPI means Universal API.
>>>
>>> Sorry for my silly question, but what's the purpose of this "Universal
>>> API" comment?
>>>
>>
>> Firstly, at least for me, I don't think it is a silly question (maybe
>> it means I should give additional explanations).  :-)
>>
>> I 'guess' the "Universal API" means:
>>
>>   "the API which can be used under multiple OS (independent from Linux), it may be used under kernel mode or user mode".
>>
>> It is just my 'guess', welcome additional suggestions or completions by
>> any members.
>>
>> When we get this correct additional explanation after discussing, if
>> suitable, I should add the final explanation to current patch.
> 
> Thanks. As this is not related at all to Linux, I don't see a reason
> to add this comment.
> 
> Here, "UAPI" means "userspace API" only.
> 

Hmm... why we need "uapi/linux/" ?  (I can not find some related
documents, so I have to 'guess').

And in my opinion, most of APIs can be independent from Linux, for in
semantics, most of them are really independent from Linux.

  e.g. net protocol, scsi protocol, usb protocol, pci protocol...

So in my opinion (ideal world), the API which is not only used under
Linux (e.g. Windows, MacOS, AIX, HPUX, SPARC ...), recommend to let
them be "Universal API".


BTW: if this patch was really applied, it seems most of files under
"include/uapi/" would need be improvement.


Thanks.

> Gr{oetje,eeting}s,
> 
>                         Geert
> 
> --
> Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert@linux-m68k.org
> 
> In personal conversations with technical people, I call myself a hacker. But
> when I'm talking to journalists I just say "programmer" or something like that.
>                                 -- Linus Torvalds
> 
> 


-- 
Chen Gang

Re: [PATCH trivial] UAPI: Kbuild: add/modify comments for "uapi/Kbuild" and "uapi/linux/Kbuild"

[Geert Uytterhoeven]

On Wed, Sep 4, 2013 at 10:09 AM, Chen Gang <gang.chen@asianux.com> wrote:
> On 09/04/2013 03:02 PM, Geert Uytterhoeven wrote:
>> On Wed, Sep 4, 2013 at 3:08 AM, Chen Gang <gang.chen@asianux.com> wrote:
>>> On 09/04/2013 12:41 AM, Geert Uytterhoeven wrote:
>>>> On Tue, Aug 6, 2013 at 3:46 AM, Chen Gang <gang.chen@asianux.com> wrote:
>>>>> --- a/include/uapi/Kbuild
>>>>> +++ b/include/uapi/Kbuild
>>>>> @@ -1,7 +1,6 @@
>>>>>  # UAPI Header export list
>>>>> -# Top-level Makefile calls into asm-$(ARCH)
>>>>> -# List only non-arch directories below
>>>>> -
>>>>> +# Except "linux/", UAPI means Universal API.
>>>>
>>>> Sorry for my silly question, but what's the purpose of this "Universal
>>>> API" comment?
>>>>
>>>
>>> Firstly, at least for me, I don't think it is a silly question (maybe
>>> it means I should give additional explanations).  :-)
>>>
>>> I 'guess' the "Universal API" means:
>>>
>>>   "the API which can be used under multiple OS (independent from Linux), it may be used under kernel mode or user mode".
>>>
>>> It is just my 'guess', welcome additional suggestions or completions by
>>> any members.
>>>
>>> When we get this correct additional explanation after discussing, if
>>> suitable, I should add the final explanation to current patch.
>>
>> Thanks. As this is not related at all to Linux, I don't see a reason
>> to add this comment.
>>
>> Here, "UAPI" means "userspace API" only.
>
> Hmm... why we need "uapi/linux/" ?  (I can not find some related
> documents, so I have to 'guess').

The "uapi" subdirectories are there to distinguish userspace headers from
kernelspace headers, and allow both to live in the kernel source tree.

When running "make headers_install", the (processed) headers in the
various "uapi" subdirectories are copied to /usr/include.
Hence "uapi/linux/foo.h" becomes <linux/foo.h> in userspace.
In userspace there are no "uapi" subdirectories anymore.

Gr{oetje,eeting}s,

                        Geert

--
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert@linux-m68k.org

In personal conversations with technical people, I call myself a hacker. But
when I'm talking to journalists I just say "programmer" or something like that.
                                -- Linus Torvalds

Re: [PATCH trivial] UAPI: Kbuild: add/modify comments for "uapi/Kbuild" and "uapi/linux/Kbuild"

[Chen Gang]

On 09/04/2013 05:02 PM, Geert Uytterhoeven wrote:
> On Wed, Sep 4, 2013 at 10:09 AM, Chen Gang <gang.chen@asianux.com> wrote:
>> On 09/04/2013 03:02 PM, Geert Uytterhoeven wrote:
>>> On Wed, Sep 4, 2013 at 3:08 AM, Chen Gang <gang.chen@asianux.com> wrote:
>>>> On 09/04/2013 12:41 AM, Geert Uytterhoeven wrote:
>>>>> On Tue, Aug 6, 2013 at 3:46 AM, Chen Gang <gang.chen@asianux.com> wrote:
>>>>>> --- a/include/uapi/Kbuild
>>>>>> +++ b/include/uapi/Kbuild
>>>>>> @@ -1,7 +1,6 @@
>>>>>>  # UAPI Header export list
>>>>>> -# Top-level Makefile calls into asm-$(ARCH)
>>>>>> -# List only non-arch directories below
>>>>>> -
>>>>>> +# Except "linux/", UAPI means Universal API.
>>>>>
>>>>> Sorry for my silly question, but what's the purpose of this "Universal
>>>>> API" comment?
>>>>>
>>>>
>>>> Firstly, at least for me, I don't think it is a silly question (maybe
>>>> it means I should give additional explanations).  :-)
>>>>
>>>> I 'guess' the "Universal API" means:
>>>>
>>>>   "the API which can be used under multiple OS (independent from Linux), it may be used under kernel mode or user mode".
>>>>
>>>> It is just my 'guess', welcome additional suggestions or completions by
>>>> any members.
>>>>
>>>> When we get this correct additional explanation after discussing, if
>>>> suitable, I should add the final explanation to current patch.
>>>
>>> Thanks. As this is not related at all to Linux, I don't see a reason
>>> to add this comment.
>>>
>>> Here, "UAPI" means "userspace API" only.
>>
>> Hmm... why we need "uapi/linux/" ?  (I can not find some related
>> documents, so I have to 'guess').
> 
> The "uapi" subdirectories are there to distinguish userspace headers from
> kernelspace headers, and allow both to live in the kernel source tree.
> 
> When running "make headers_install", the (processed) headers in the
> various "uapi" subdirectories are copied to /usr/include.
> Hence "uapi/linux/foo.h" becomes <linux/foo.h> in userspace.
> In userspace there are no "uapi" subdirectories anymore.
> 

Yeah, so why need another "uapi/*" excluding "uapi/linux" ?

Are they also truly still "Userspace API" but which need not distinguish
? (at least, it seems that idea is not quite good).

Hmm... maybe the "uapi/*" except "uapi/linux" are also installed? Is it
for compatible (originally they are here, and now we have to follow, it
is no reason to change if not find related critical issues)?


Thanks.

> Gr{oetje,eeting}s,
> 
>                         Geert
> 
> --
> Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert@linux-m68k.org
> 
> In personal conversations with technical people, I call myself a hacker. But
> when I'm talking to journalists I just say "programmer" or something like that.
>                                 -- Linus Torvalds
> 
> 


-- 
Chen Gang

Re: [PATCH trivial] UAPI: Kbuild: add/modify comments for "uapi/Kbuild" and "uapi/linux/Kbuild"

[Geert Uytterhoeven]

On Wed, Sep 4, 2013 at 11:13 AM, Chen Gang <gang.chen@asianux.com> wrote:
>>> Hmm... why we need "uapi/linux/" ?  (I can not find some related
>>> documents, so I have to 'guess').
>>
>> The "uapi" subdirectories are there to distinguish userspace headers from
>> kernelspace headers, and allow both to live in the kernel source tree.
>>
>> When running "make headers_install", the (processed) headers in the
>> various "uapi" subdirectories are copied to /usr/include.
>> Hence "uapi/linux/foo.h" becomes <linux/foo.h> in userspace.
>> In userspace there are no "uapi" subdirectories anymore.
>>
>
> Yeah, so why need another "uapi/*" excluding "uapi/linux" ?
>
> Are they also truly still "Userspace API" but which need not distinguish
> ? (at least, it seems that idea is not quite good).
>
> Hmm... maybe the "uapi/*" except "uapi/linux" are also installed? Is it
> for compatible (originally they are here, and now we have to follow, it
> is no reason to change if not find related critical issues)?

All uapi files are installed, a.o. /usr/include/scsi/, /usr/include/video/, ...

Historically, everything under "include" in the kernel source tree was
installed in /usr/include/, after (semi)manual cleanup.
Since the uapi split, everything is handled automatically.
Because of compatibility reasons (do not break userspace), paths had to
stay the same.

Gr{oetje,eeting}s,

                        Geert

--
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert@linux-m68k.org

In personal conversations with technical people, I call myself a hacker. But
when I'm talking to journalists I just say "programmer" or something like that.
                                -- Linus Torvalds

Re: [PATCH trivial] UAPI: Kbuild: add/modify comments for "uapi/Kbuild" and "uapi/linux/Kbuild"

[Chen Gang]

On 09/04/2013 05:27 PM, Geert Uytterhoeven wrote:
> On Wed, Sep 4, 2013 at 11:13 AM, Chen Gang <gang.chen@asianux.com> wrote:
>>>> Hmm... why we need "uapi/linux/" ?  (I can not find some related
>>>> documents, so I have to 'guess').
>>>
>>> The "uapi" subdirectories are there to distinguish userspace headers from
>>> kernelspace headers, and allow both to live in the kernel source tree.
>>>
>>> When running "make headers_install", the (processed) headers in the
>>> various "uapi" subdirectories are copied to /usr/include.
>>> Hence "uapi/linux/foo.h" becomes <linux/foo.h> in userspace.
>>> In userspace there are no "uapi" subdirectories anymore.
>>>
>>
>> Yeah, so why need another "uapi/*" excluding "uapi/linux" ?
>>
>> Are they also truly still "Userspace API" but which need not distinguish
>> ? (at least, it seems that idea is not quite good).
>>
>> Hmm... maybe the "uapi/*" except "uapi/linux" are also installed? Is it
>> for compatible (originally they are here, and now we have to follow, it
>> is no reason to change if not find related critical issues)?
> 
> All uapi files are installed, a.o. /usr/include/scsi/, /usr/include/video/, ...
> 

Oh, sorry, I misunderstand your original mail contents.

> Historically, everything under "include" in the kernel source tree was
> installed in /usr/include/, after (semi)manual cleanup.
> Since the uapi split, everything is handled automatically.
> Because of compatibility reasons (do not break userspace), paths had to
> stay the same.
> 

At least for me, that sounds reasonable.

Hmm... when some members need add a new Userspace API. I guess:

  if it is related with one of existent "uapi/*" sub-directory (except "uapi/linux"), they need put the file(or directory) under the related "uapi/*",

  if can not find existent "uapi/*" sub-directory, they need put the file(or directory) under "uapi/linux/*".

Does it sound reasonable ?


Thanks.

> Gr{oetje,eeting}s,
> 
>                         Geert
> 
> --
> Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert@linux-m68k.org
> 
> In personal conversations with technical people, I call myself a hacker. But
> when I'm talking to journalists I just say "programmer" or something like that.
>                                 -- Linus Torvalds
> 
> 


-- 
Chen Gang

Re: [PATCH trivial] UAPI: Kbuild: add/modify comments for "uapi/Kbuild" and "uapi/linux/Kbuild"

[Chen Gang]

On 09/04/2013 05:38 PM, Chen Gang wrote:
> On 09/04/2013 05:27 PM, Geert Uytterhoeven wrote:
>> On Wed, Sep 4, 2013 at 11:13 AM, Chen Gang <gang.chen@asianux.com> wrote:
>>>>> Hmm... why we need "uapi/linux/" ?  (I can not find some related
>>>>> documents, so I have to 'guess').
>>>>
>>>> The "uapi" subdirectories are there to distinguish userspace headers from
>>>> kernelspace headers, and allow both to live in the kernel source tree.
>>>>
>>>> When running "make headers_install", the (processed) headers in the
>>>> various "uapi" subdirectories are copied to /usr/include.
>>>> Hence "uapi/linux/foo.h" becomes <linux/foo.h> in userspace.
>>>> In userspace there are no "uapi" subdirectories anymore.
>>>>
>>>
>>> Yeah, so why need another "uapi/*" excluding "uapi/linux" ?
>>>
>>> Are they also truly still "Userspace API" but which need not distinguish
>>> ? (at least, it seems that idea is not quite good).
>>>
>>> Hmm... maybe the "uapi/*" except "uapi/linux" are also installed? Is it
>>> for compatible (originally they are here, and now we have to follow, it
>>> is no reason to change if not find related critical issues)?
>>
>> All uapi files are installed, a.o. /usr/include/scsi/, /usr/include/video/, ...
>>
> 
> Oh, sorry, I misunderstand your original mail contents.
> 
>> Historically, everything under "include" in the kernel source tree was
>> installed in /usr/include/, after (semi)manual cleanup.
>> Since the uapi split, everything is handled automatically.
>> Because of compatibility reasons (do not break userspace), paths had to
>> stay the same.
>>
> 
> At least for me, that sounds reasonable.
> 
> Hmm... when some members need add a new Userspace API. I guess:
> 
>   if it is related with one of existent "uapi/*" sub-directory (except "uapi/linux"), they need put the file(or directory) under the related "uapi/*",
> 
>   if can not find existent "uapi/*" sub-directory, they need put the file(or directory) under "uapi/linux/*".
> 

Hmm... if "uapi/*" are really only for compatible, better to keep them
no touch, that means: should always add new file(or directory) under
"uapi/linux/" sub-directory (even if they are related with "uapi/*").


Thanks.

> Does it sound reasonable ?
> 
> 
> Thanks.
> 
>> Gr{oetje,eeting}s,
>>
>>                         Geert
>>
>> --
>> Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert@linux-m68k.org
>>
>> In personal conversations with technical people, I call myself a hacker. But
>> when I'm talking to journalists I just say "programmer" or something like that.
>>                                 -- Linus Torvalds
>>
>>
> 
> 


-- 
Chen Gang