[PATCH] doc: ioctl: Add some clarifications to botching-up-ioctls

[PATCH] doc: ioctl: Add some clarifications to botching-up-ioctls

[Laura Abbott]

- 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 <labbott@redhat.com>
---
I can split these into two separate patches if necessary but it seemed simpler
just to colapse them into a single patch.
---
 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 cc30b14..36138c6 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
-- 
2.7.4

Re: [PATCH] doc: ioctl: Add some clarifications to botching-up-ioctls

[Arnd Bergmann]

On Friday, September 2, 2016 3:42:24 PM CEST Laura Abbott wrote:
> - 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 <labbott@redhat.com>
> 

Looks good to me,

Acked-by: Arnd Bergmann <arnd@arndb.de>

Re: [PATCH] doc: ioctl: Add some clarifications to botching-up-ioctls

[Jonathan Corbet]

On Sat, 03 Sep 2016 00:44:02 +0200
Arnd Bergmann <arnd@arndb.de> wrote:

> On Friday, September 2, 2016 3:42:24 PM CEST Laura Abbott wrote:
> > - 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 <labbott@redhat.com>
> >   
> 
> Looks good to me,
> 
> Acked-by: Arnd Bergmann <arnd@arndb.de>

Applied to the docs tree, thanks.

jon