[PATCH] doc: monospace style for inline code in botching ioctl

[PATCH] doc: monospace style for inline code in botching ioctl

[Federico Vaga]

Highlighting inline code improves text readability.

Signed-off-by: Federico Vaga <federico.vaga@vaga.pv.it>
---
 Documentation/process/botching-up-ioctls.rst | 24 ++++++++++----------
 1 file changed, 12 insertions(+), 12 deletions(-)

diff --git a/Documentation/process/botching-up-ioctls.rst b/Documentation/process/botching-up-ioctls.rst
index 9739b88463a5..b57a979c6438 100644
--- a/Documentation/process/botching-up-ioctls.rst
+++ b/Documentation/process/botching-up-ioctls.rst
@@ -28,7 +28,7 @@ First the prerequisites. Without these you have already failed, because you
 will need to add a 32-bit compat layer:
 
  * Only use fixed sized integers. To avoid conflicts with typedefs in userspace
-   the kernel has special types like __u32, __s64. Use them.
+   the kernel has special types like ``__u32``, ``__s64``. Use them.
 
  * Align everything to the natural size and use explicit padding. 32-bit
    platforms don't necessarily align 64-bit values to 64-bit boundaries, but
@@ -41,12 +41,12 @@ will need to add a 32-bit compat layer:
    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 uintptr_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. The macro
-   u64_to_user_ptr can be used in the kernel to avoid warnings about integers
-   and pointers of different sizes.
+ * Pointers are ``__u64``, cast from/to a ``uintptr_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. The macro
+   ``u64_to_user_ptr`` can be used in the kernel to avoid warnings about
+   integers and pointers of different sizes.
 
 
 Basics
@@ -132,8 +132,8 @@ wait for outstanding ones. This is really tricky business; at the moment none of
 the ioctls supported by the drm/i915 get this fully right, which means there's
 still tons more lessons to learn here.
 
- * Use CLOCK_MONOTONIC as your reference time, always. It's what alsa, drm and
-   v4l use by default nowadays. But let userspace know which timestamps are
+ * Use ``CLOCK_MONOTONIC`` as your reference time, always. It's what alsa, drm
+   and v4l use by default nowadays. But let userspace know which timestamps are
    derived from different clock domains like your main system clock (provided
    by the kernel) or some independent hardware counter somewhere else. Clocks
    will mismatch if you look close enough, but if performance measuring tools
@@ -141,8 +141,8 @@ still tons more lessons to learn here.
    get at the raw values of some clocks (e.g. through in-command-stream
    performance counter sampling instructions) consider exposing those also.
 
- * Use __s64 seconds plus __u64 nanoseconds to specify time. It's not the most
-   convenient time specification, but it's mostly the standard.
+ * Use ``__s64`` seconds plus ``__u64`` nanoseconds to specify time. It's not
+   the most convenient time specification, but it's mostly the standard.
 
  * Check that input time values are normalized and reject them if not. Note
    that the kernel native struct ktime has a signed integer for both seconds
@@ -178,7 +178,7 @@ entails its own little set of pitfalls:
    needs to be shared across processes -  fd-passing over unix domain sockets
    also simplifies lifetime management for userspace.
 
- * Always have O_CLOEXEC support.
+ * Always have ``O_CLOEXEC`` support.
 
  * Ensure that you have sufficient insulation between different clients. By
    default pick a private per-fd namespace which forces any sharing to be done
-- 
2.30.2

Re: [PATCH] doc: monospace style for inline code in botching ioctl

[Matthew Wilcox]

On Sun, Jan 01, 2023 at 02:27:58PM +0100, Federico Vaga wrote:
> +   that diminishes the checking tools like sparse can provide. The macro
> +   ``u64_to_user_ptr`` can be used in the kernel to avoid warnings about

Should probably be u64_to_user_ptr() instead to get both the monospace &
the hyperlink.

Re: [PATCH] doc: monospace style for inline code in botching ioctl

[Federico Vaga]

On Mon, Jan 02, 2023 at 02:44:22PM +0000, Matthew Wilcox wrote:
>On Sun, Jan 01, 2023 at 02:27:58PM +0100, Federico Vaga wrote:
>> +   that diminishes the checking tools like sparse can provide. The macro
>> +   ``u64_to_user_ptr`` can be used in the kernel to avoid warnings about
>
>Should probably be u64_to_user_ptr() instead to get both the monospace &
>the hyperlink.

Indeed, good point. A V2 will come

-- 
Federico Vaga