[PATCH 0/2] Documentation: ioctl-number: DRY cleanup

[PATCH 0/2] Documentation: ioctl-number: DRY cleanup

[Bagas Sanjaya]

As the subject suggests: don't repeat yourself (DRY) on table introduction
(ioctl macros-related).

Enjoy!

Bagas Sanjaya (2):
  Documentation: ioctl-number: Shorten macros table
  Documentation: ioctl-number: Don't repeat macro names

 .../userspace-api/ioctl/ioctl-number.rst      | 36 ++++++++++---------
 1 file changed, 20 insertions(+), 16 deletions(-)

base-commit: f55b3ca3cf1d1652c4b3481b671940461331d69f
-- 
An old man doll... just what I always wanted! - Clara

[PATCH 1/2] Documentation: ioctl-number: Shorten macros table

[Bagas Sanjaya]

The macros table has three columns: the second one is "an" and the
third one writes "an ioctl with ... parameters". Simplify the table
by adding heading row that indicates macro name and accepted
parameters.

Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 Documentation/userspace-api/ioctl/ioctl-number.rst | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

diff --git a/Documentation/userspace-api/ioctl/ioctl-number.rst b/Documentation/userspace-api/ioctl/ioctl-number.rst
index bc91756bde733b..ad5e7001f59137 100644
--- a/Documentation/userspace-api/ioctl/ioctl-number.rst
+++ b/Documentation/userspace-api/ioctl/ioctl-number.rst
@@ -10,12 +10,14 @@ Michael Elizabeth Chastain
 If you are adding new ioctl's to the kernel, you should use the _IO
 macros defined in <linux/ioctl.h>:
 
-    ====== == ============================================
-    _IO    an ioctl with no parameters
-    _IOW   an ioctl with write parameters (copy_from_user)
-    _IOR   an ioctl with read parameters  (copy_to_user)
-    _IOWR  an ioctl with both write and read parameters.
-    ====== == ============================================
+    ====== ===========================
+    macro  parameters
+    ====== ===========================
+    _IO    none
+    _IOW   write (read from userspace)
+    _IOR   read (write to userpace)
+    _IOWR  write and read
+    ====== ===========================
 
 'Write' and 'read' are from the user's point of view, just like the
 system calls 'write' and 'read'.  For example, a SET_FOO ioctl would
-- 
An old man doll... just what I always wanted! - Clara

[PATCH 2/2] Documentation: ioctl-number: Don't repeat macro names

[Bagas Sanjaya]

Don't repeat mentioning macro names (_IO, _IOW, _IOR, and _IOWR) to
keep the wording effective.

Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
 .../userspace-api/ioctl/ioctl-number.rst      | 22 ++++++++++---------
 1 file changed, 12 insertions(+), 10 deletions(-)

diff --git a/Documentation/userspace-api/ioctl/ioctl-number.rst b/Documentation/userspace-api/ioctl/ioctl-number.rst
index ad5e7001f59137..16994ce3a6c576 100644
--- a/Documentation/userspace-api/ioctl/ioctl-number.rst
+++ b/Documentation/userspace-api/ioctl/ioctl-number.rst
@@ -25,9 +25,9 @@ be _IOW, although the kernel would actually read data from user space;
 a GET_FOO ioctl would be _IOR, although the kernel would actually write
 data to user space.
 
-The first argument to _IO, _IOW, _IOR, or _IOWR is an identifying letter
-or number from the table below.  Because of the large number of drivers,
-many drivers share a partial letter with other drivers.
+The first argument to the macros is an identifying letter or number from
+the table below. Because of the large number of drivers, many drivers
+share a partial letter with other drivers.
 
 If you are writing a driver for a new device and need a letter, pick an
 unused block with enough room for expansion: 32 to 256 ioctl commands
@@ -35,12 +35,14 @@ should suffice. You can register the block by patching this file and
 submitting the patch through :doc:`usual patch submission process
 </process/submitting-patches>`.
 
-The second argument to _IO, _IOW, _IOR, or _IOWR is a sequence number
-to distinguish ioctls from each other.  The third argument to _IOW,
-_IOR, or _IOWR is the type of the data going into the kernel or coming
-out of the kernel (e.g.  'int' or 'struct foo').  NOTE!  Do NOT use
-sizeof(arg) as the third argument as this results in your ioctl thinking
-it passes an argument of type size_t.
+The second argument is a sequence number to distinguish ioctls from each
+other. The third argument (not applicable to _IO) is the type of the data
+going into the kernel or coming out of the kernel (e.g.  'int' or
+'struct foo').
+
+.. note::
+   Do NOT use sizeof(arg) as the third argument as this results in your
+   ioctl thinking it passes an argument of type size_t.
 
 Some devices use their major number as the identifier; this is OK, as
 long as it is unique.  Some devices are irregular and don't follow any
@@ -53,7 +55,7 @@ Following this convention is good because:
     error rather than some unexpected behaviour.
 
 (2) The 'strace' build procedure automatically finds ioctl numbers
-    defined with _IO, _IOW, _IOR, or _IOWR.
+    defined with the macros.
 
 (3) 'strace' can decode numbers back into useful names when the
     numbers are unique.
-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH 0/2] Documentation: ioctl-number: DRY cleanup

[Jonathan Corbet]

Bagas Sanjaya <bagasdotme@gmail.com> writes:

> As the subject suggests: don't repeat yourself (DRY) on table introduction
> (ioctl macros-related).
>
> Enjoy!
>
> Bagas Sanjaya (2):
>   Documentation: ioctl-number: Shorten macros table
>   Documentation: ioctl-number: Don't repeat macro names
>
>  .../userspace-api/ioctl/ioctl-number.rst      | 36 ++++++++++---------
>  1 file changed, 20 insertions(+), 16 deletions(-)

The first seems like a good cleanup; the second a bit less so, but I've
applied the pair.

Thanks,

jon