From c6517b78153a1ffb401d8c3ec329effd3ee19036 Mon Sep 17 00:00:00 2001 From: Laura Abbott Date: Fri, 2 Sep 2016 15:42:24 -0700 Subject: [PATCH 1/5] doc: ioctl: Add some clarifications to botching-up-ioctls - The guide currently says to pad the structure to a multiple of 64-bits. This is not necessary in cases where the structure contains no 64-bit types. Clarify this concept to avoid unnecessary padding. - When using __u64 to hold user pointers, blindly trying to do a cast to a void __user * may generate a warning on 32-bit systems about a cast from an integer to a pointer of different size. There is a macro to deal with this which hides an ugly double cast. Add a reference to this macro. Signed-off-by: Laura Abbott Acked-by: Arnd Bergmann Signed-off-by: Jonathan Corbet --- Documentation/ioctl/botching-up-ioctls.txt | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/Documentation/ioctl/botching-up-ioctls.txt b/Documentation/ioctl/botching-up-ioctls.txt index cc30b14791cb..36138c632f7a 100644 --- a/Documentation/ioctl/botching-up-ioctls.txt +++ b/Documentation/ioctl/botching-up-ioctls.txt @@ -34,15 +34,18 @@ will need to add a a 32-bit compat layer: 64-bit platforms do. So we always need padding to the natural size to get this right. - * Pad the entire struct to a multiple of 64-bits - the structure size will - otherwise differ on 32-bit versus 64-bit. Having a different structure size - hurts when passing arrays of structures to the kernel, or if the kernel - checks the structure size, which e.g. the drm core does. + * Pad the entire struct to a multiple of 64-bits if the structure contains + 64-bit types - the structure size will otherwise differ on 32-bit versus + 64-bit. Having a different structure size hurts when passing arrays of + structures to the kernel, or if the kernel checks the structure size, which + e.g. the drm core does. * Pointers are __u64, cast from/to a uintprt_t on the userspace side and from/to a void __user * in the kernel. Try really hard not to delay this conversion or worse, fiddle the raw __u64 through your code since that - diminishes the checking tools like sparse can provide. + diminishes the checking tools like sparse can provide. The macro + u64_to_user_ptr can be used in the kernel to avoid warnings about integers + and pointres of different sizes. Basics From 2836a2f5bd8516ae3c1a9b8bd76aea2160e5d092 Mon Sep 17 00:00:00 2001 From: Finn Thain Date: Sat, 27 Aug 2016 12:29:59 +1000 Subject: [PATCH 2/5] documentation/scsi: Remove nodisconnect parameter The driver that used the 'nodisconnect' parameter was removed in commit 565bae6a4a8f ("[SCSI] 53c7xx: kill driver"). Related documentation was cleaned up in commit f37a7238d379 ("[SCSI] 53c7xx: fix removal fallout"), except for the remaining two mentions that are removed here. Signed-off-by: Finn Thain Reviewed-by: Geert Uytterhoeven Signed-off-by: Jonathan Corbet --- Documentation/kernel-parameters.txt | 2 -- Documentation/scsi/scsi-parameters.txt | 2 -- 2 files changed, 4 deletions(-) diff --git a/Documentation/kernel-parameters.txt b/Documentation/kernel-parameters.txt index 1fa28092ec00..861f57514fbd 100644 --- a/Documentation/kernel-parameters.txt +++ b/Documentation/kernel-parameters.txt @@ -2574,8 +2574,6 @@ bytes respectively. Such letter suffixes can also be entirely omitted. nodelayacct [KNL] Disable per-task delay accounting - nodisconnect [HW,SCSI,M68K] Disables SCSI disconnects. - nodsp [SH] Disable hardware DSP at boot time. noefi Disable EFI runtime services support. diff --git a/Documentation/scsi/scsi-parameters.txt b/Documentation/scsi/scsi-parameters.txt index 1241ac11edb1..d5ae6ced6be3 100644 --- a/Documentation/scsi/scsi-parameters.txt +++ b/Documentation/scsi/scsi-parameters.txt @@ -79,8 +79,6 @@ parameters may be changed at runtime by the command ncr53c8xx= [HW,SCSI] - nodisconnect [HW,SCSI,M68K] Disables SCSI disconnects. - osst= [HW,SCSI] SCSI Tape Driver Format: , See also Documentation/scsi/st.txt. From 9d9cce7f10dc8d7a5fc6ef4e537e17664234605a Mon Sep 17 00:00:00 2001 From: Lorenzo Stoakes Date: Tue, 23 Aug 2016 09:00:45 +0100 Subject: [PATCH 3/5] x86: fix memory ranges in mm documentation This is a trivial fix to correct upper bound addresses to always be inclusive. Previously, the majority of ranges specified were inclusive with a small minority specifying an exclusive upper bound. This patch fixes this inconsistency. Signed-off-by: Lorenzo Stoakes Signed-off-by: Jonathan Corbet --- Documentation/x86/x86_64/mm.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Documentation/x86/x86_64/mm.txt b/Documentation/x86/x86_64/mm.txt index 8c7dd5957ae1..5724092db811 100644 --- a/Documentation/x86/x86_64/mm.txt +++ b/Documentation/x86/x86_64/mm.txt @@ -12,13 +12,13 @@ ffffc90000000000 - ffffe8ffffffffff (=45 bits) vmalloc/ioremap space ffffe90000000000 - ffffe9ffffffffff (=40 bits) hole ffffea0000000000 - ffffeaffffffffff (=40 bits) virtual memory map (1TB) ... unused hole ... -ffffec0000000000 - fffffc0000000000 (=44 bits) kasan shadow memory (16TB) +ffffec0000000000 - fffffbffffffffff (=44 bits) kasan shadow memory (16TB) ... unused hole ... ffffff0000000000 - ffffff7fffffffff (=39 bits) %esp fixup stacks ... unused hole ... -ffffffef00000000 - ffffffff00000000 (=64 GB) EFI region mapping space +ffffffef00000000 - fffffffeffffffff (=64 GB) EFI region mapping space ... unused hole ... -ffffffff80000000 - ffffffffa0000000 (=512 MB) kernel text mapping, from phys 0 +ffffffff80000000 - ffffffff9fffffff (=512 MB) kernel text mapping, from phys 0 ffffffffa0000000 - ffffffffff5fffff (=1526 MB) module mapping space ffffffffff600000 - ffffffffffdfffff (=8 MB) vsyscalls ffffffffffe00000 - ffffffffffffffff (=2 MB) unused hole From ef00028b20481647431ca8bffe5469fb86cf154f Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Fri, 26 Aug 2016 07:14:08 -0600 Subject: [PATCH 4/5] docs: make kernel-doc handle varargs properly As far as I can tell, the handling of "..." arguments has never worked right, so any documentation provided was ignored in favor of "variable arguments." This makes kernel-doc handle "@...:" as documented. It does *not* fix spots in kerneldoc comments that don't follow that convention, but they are no more broken than before. Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 301bf874cac8..c5918951a8d3 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -412,7 +412,7 @@ my $doc_com_body = '\s*\* ?'; my $doc_decl = $doc_com . '(\w+)'; # @params and a strictly limited set of supported section names my $doc_sect = $doc_com . - '\s*(\@\w+|description|context|returns?|notes?|examples?)\s*:(.*)'; + '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:(.*)'; my $doc_content = $doc_com_body . '(.*)'; my $doc_block = $doc_com . 'DOC:\s*(.*)?'; my $doc_inline_start = '^\s*/\*\*\s*$'; @@ -2351,6 +2351,7 @@ sub push_parameter($$$) { if ($type eq "" && $param =~ /\.\.\.$/) { + $param = "..."; if (!defined $parameterdescs{$param} || $parameterdescs{$param} eq "") { $parameterdescs{$param} = "variable arguments"; } From 5219f18aaf00f9f9ba572b3817e394043388d4ef Mon Sep 17 00:00:00 2001 From: Jonathan Corbet Date: Wed, 24 Aug 2016 16:31:15 -0600 Subject: [PATCH 5/5] docs: Special-case function-pointer parameters in kernel-doc Add yet another regex to kernel-doc to trap @param() references separately and not produce corrupt RST markup. Signed-off-by: Jonathan Corbet --- scripts/kernel-doc | 2 ++ 1 file changed, 2 insertions(+) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index c5918951a8d3..93721f3c91bf 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -212,6 +212,7 @@ my $anon_struct_union = 0; my $type_constant = '\%([-_\w]+)'; my $type_func = '(\w+)\(\)'; my $type_param = '\@(\w+)'; +my $type_fp_param = '\@(\w+)\(\)'; # Special RST handling for func ptr params my $type_struct = '\&((struct\s*)*[_\w]+)'; my $type_struct_xml = '\\&((struct\s*)*[_\w]+)'; my $type_env = '(\$\w+)'; @@ -292,6 +293,7 @@ my @highlights_rst = ( # Note: need to escape () to avoid func matching later [$type_member_func, "\\:c\\:type\\:`\$1\$2\\\\(\\\\) <\$1>`"], [$type_member, "\\:c\\:type\\:`\$1\$2 <\$1>`"], + [$type_fp_param, "**\$1\\\\(\\\\)**"], [$type_func, "\\:c\\:func\\:`\$1()`"], [$type_struct_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"], [$type_enum_full, "\\:c\\:type\\:`\$1 \$2 <\$2>`"],