Documentation: ioctl-number: DRY cleanup
cover Documentation: ioctl-number: DRY cleanup
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
Signature · 1 line
An old man doll... just what I always wanted! - Clara
PATCH 1/2 Documentation: ioctl-number: Shorten macros table
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.
--- Documentation/userspace-api/ioctl/ioctl-number.rst | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-)
Documentation/userspace-api/ioctl/ioctl-number.rst +8 -6
@@ -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
Signature · 1 line
An old man doll... just what I always wanted! - Clara
PATCH 2/2 Documentation: ioctl-number: Don't repeat macro names
In reply to Bagas SanjayaDon't repeat mentioning macro names (_IO, _IOW, _IOR, and _IOWR) to keep the wording effective.
--- .../userspace-api/ioctl/ioctl-number.rst | 22 ++++++++++--------- 1 file changed, 12 insertions(+), 10 deletions(-)
Documentation/userspace-api/ioctl/ioctl-number.rst +12 -10
@@ -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.
Signature · 1 line
An old man doll... just what I always wanted! - Clara
Jonathan Corbet
maintainerQuoted 11 lines · 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(-)
The first seems like a good cleanup; the second a bit less so, but I've applied the pair.
Thanks,
jon