Skip to contentSkip to conversation

UAPI: Kbuild: add/modify comments for "uapi/Kbuild" and "uapi/linux/Kbuild"

PATCH Superseded Chen Gang 4 participants 23 messages Aug 6, 2013 – Oct 1, 2013

lore
Share & tools
lore

Chen Gang

author
#0 lore raw

PATCH 1/1 UAPI: Kbuild: add/modify comments for "uapi/Kbuild" and "uapi/linux/Kbuild"

"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".

---
 include/uapi/Kbuild       |    5 ++---
 include/uapi/linux/Kbuild |    2 ++
 2 files changed, 4 insertions(+), 3 deletions(-)
include/uapi/Kbuild +2 -3
index 81d2106..c682891 100644
@@ -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/
include/uapi/linux/Kbuild +2 -0
index 997f9f2..0025e07 100644
@@ -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/
Signature · 1 line
1.7.7.6
#1 lore raw
Quoted 2 lines · Chen Gang

"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.

author
#2 lore raw
Quoted 7 lines · Joe Perches
Quoted 2 lines · Chen Gang

"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.

Signature · 1 line
Chen Gang
#3 lore raw
In reply to Joe Perches
Quoted 7 lines · Joe Perches
Quoted 1 line · Chen Gang

"include/uapi/" is the whole Linux kernel API, it is important

enough

Quoted 1 line

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

author
#4 lore raw
Quoted 5 lines · Rob Landley
Quoted 4 lines · Joe Perches
Quoted 2 lines · Chen Gang

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

Quoted 8 lines
Quoted 2 lines

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.

Quoted 4 lines

(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 ?

Quoted 2 lines

Rob

Signature · 1 line
Chen Gang
author
#5 lore raw

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.

Quoted 42 lines · Chen Gang
Quoted 5 lines · Rob Landley
Quoted 4 lines · Joe Perches
Quoted 2 lines · Chen Gang

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

Quoted 8 lines
Quoted 2 lines

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.

Quoted 4 lines

(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 ?

Quoted 2 lines

Rob

Signature · 1 line
Chen Gang
author
#6 lore raw

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.

Quoted 61 lines · 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.

Quoted 42 lines · Chen Gang
Quoted 5 lines · Rob Landley
Quoted 4 lines · Joe Perches
Quoted 2 lines · Chen Gang

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

Quoted 8 lines
Quoted 2 lines

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.

Quoted 4 lines

(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 ?

Quoted 2 lines

Rob

Signature · 1 line
Chen Gang
author
#7 lore raw

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".

---
 include/uapi/Kbuild       |    5 ++---
 include/uapi/linux/Kbuild |    2 ++
 2 files changed, 4 insertions(+), 3 deletions(-)
include/uapi/Kbuild +2 -3
index 81d2106..c682891 100644
@@ -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/
include/uapi/linux/Kbuild +2 -0
index 997f9f2..0025e07 100644
@@ -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/
Signature · 6 lines
1.7.7.6

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


Thanks.
Quoted 103 lines · 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.

Quoted 61 lines · 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.

Quoted 42 lines · Chen Gang
Quoted 5 lines · Rob Landley
Quoted 4 lines · Joe Perches
Quoted 2 lines · Chen Gang

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

Quoted 8 lines
Quoted 2 lines

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.

Quoted 4 lines

(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 ?

Quoted 2 lines

Rob

Signature · 1 line
Chen Gang
author
#8 lore raw

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.

Quoted 59 lines · 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".

---
 include/uapi/Kbuild       |    5 ++---
 include/uapi/linux/Kbuild |    2 ++
 2 files changed, 4 insertions(+), 3 deletions(-)
include/uapi/Kbuild +2 -3
index 81d2106..c682891 100644
@@ -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/
include/uapi/linux/Kbuild +2 -0
index 997f9f2..0025e07 100644
@@ -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/
Signature · 1 line
Chen Gang
author
#9 lore raw

PATCH v2 1/1 UAPI: Kbuild: add/modify comments for "uapi/Kbuild" and "uapi/linux/Kbuild"

"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",

---
 include/uapi/Kbuild |    7 ++++---
 1 files changed, 4 insertions(+), 3 deletions(-)
include/uapi/Kbuild +4 -3
index 81d2106..287e8d0 100644
@@ -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/
Signature · 1 line
1.7.7.6
author
#10 lore raw

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

Quoted 31 lines · 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",

---
 include/uapi/Kbuild |    7 ++++---
 1 files changed, 4 insertions(+), 3 deletions(-)
include/uapi/Kbuild +4 -3
index 81d2106..287e8d0 100644
@@ -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/
Signature · 1 line
Chen Gang
author
#11 lore raw

PATCH v3 1/1 include/uapi/Kbuild: modify the comments for it

In reply to 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",

---
 include/uapi/Kbuild |    7 ++++---
 1 files changed, 4 insertions(+), 3 deletions(-)
include/uapi/Kbuild +4 -3
index 81d2106..287e8d0 100644
@@ -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/
Signature · 1 line
1.7.7.6
author
#12 lore raw

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

Quoted 6 lines · 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.

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". :-)

Quoted 2 lines

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.

Quoted 23 lines
---
 include/uapi/Kbuild |    7 ++++---
 1 files changed, 4 insertions(+), 3 deletions(-)
include/uapi/Kbuild +4 -3
index 81d2106..287e8d0 100644
@@ -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/
Signature · 1 line
Chen Gang
author
#13 lore raw

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

In reply to 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".

---
 include/uapi/Kbuild |   13 +++++++++++--
 1 files changed, 11 insertions(+), 2 deletions(-)
include/uapi/Kbuild +11 -2
index 81d2106..f396115 100644
@@ -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/
Signature · 1 line
1.7.7.6
#14 lore raw
In reply to Chen Gang

include/uapi/Kbuild line 2

Quoted 8 lines · Chen Gang
include/uapi/Kbuild +1 -3
@@ -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?

include/uapi/Kbuild line 6

Quoted 4 lines
include/uapi/Kbuild +1 -0
+# 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 -- [email protected]

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

author
#15 lore raw
Quoted 13 lines · Geert Uytterhoeven

include/uapi/Kbuild line 2

Quoted 8 lines · Chen Gang
include/uapi/Kbuild +1 -3
@@ -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.

Quoted 17 lines

include/uapi/Kbuild line 6

Quoted 4 lines
include/uapi/Kbuild +1 -0
+# 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 -- [email protected]

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

Signature · 1 line
Chen Gang
#16 lore raw
Quoted 20 lines · Chen Gang
Quoted 13 lines · Geert Uytterhoeven

include/uapi/Kbuild line 2

Quoted 8 lines · Chen Gang
include/uapi/Kbuild +1 -3
@@ -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:

Quoted 7 lines

"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 -- [email protected]

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

author
#17 lore raw
Quoted 26 lines · Geert Uytterhoeven
Quoted 25 lines · Chen Gang
Quoted 13 lines · Geert Uytterhoeven

include/uapi/Kbuild line 2

Quoted 8 lines · Chen Gang
include/uapi/Kbuild +1 -3
@@ -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.

Quoted 8 lines
Quoted 2 lines

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.

Quoted 12 lines

Gr{oetje,eeting}s,

Geert

--
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- [email protected]

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

Signature · 1 line
Chen Gang
#18 lore raw
Quoted 30 lines · Chen Gang
Quoted 29 lines · Geert Uytterhoeven
Quoted 27 lines · Chen Gang
Quoted 13 lines · Geert Uytterhoeven

include/uapi/Kbuild line 2

Quoted 8 lines · Chen Gang
include/uapi/Kbuild +1 -3
@@ -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.

Quoted 7 lines
Quoted 4 lines

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 -- [email protected]

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

author
#19 lore raw
Quoted 39 lines · Geert Uytterhoeven
Quoted 30 lines · Chen Gang
Quoted 29 lines · Geert Uytterhoeven
Quoted 27 lines · Chen Gang
Quoted 13 lines · Geert Uytterhoeven

include/uapi/Kbuild line 2

Quoted 8 lines · Chen Gang
include/uapi/Kbuild +1 -3
@@ -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.

Quoted 7 lines
Quoted 4 lines

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').

Quoted 8 lines

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.

Quoted 12 lines

Gr{oetje,eeting}s,

Geert

--
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- [email protected]

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

Signature · 1 line
Chen Gang
#20 lore raw
Quoted 12 lines · Chen Gang
Quoted 11 lines
Quoted 2 lines

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.

Quoted 8 lines

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 -- [email protected]

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

author
#21 lore raw
Quoted 15 lines · Geert Uytterhoeven
Quoted 14 lines · Chen Gang
Quoted 11 lines
Quoted 2 lines

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" ?

Quoted 9 lines
Quoted 6 lines

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.

Quoted 6 lines

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.

Quoted 12 lines

Gr{oetje,eeting}s,

Geert

--
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- [email protected]

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

Signature · 1 line
Chen Gang
author
#22 lore raw
Quoted 35 lines · Chen Gang
Quoted 15 lines · Geert Uytterhoeven
Quoted 14 lines · Chen Gang
Quoted 11 lines
Quoted 2 lines

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" ?

Quoted 9 lines
Quoted 6 lines

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.

Quoted 6 lines

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.

Quoted 8 lines

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.

Quoted 19 lines

Does it sound reasonable ?

Thanks.

Quoted 12 lines

Gr{oetje,eeting}s,

Geert

--
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- [email protected]

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

Signature · 1 line
Chen Gang