lkml.org 
[lkml]   [2023]   [Jan]   [1]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
Patch in this message
/
From
Subject[PATCH] doc: monospace style for inline code in botching ioctl
Date
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
\
 
 \ /
  Last update: 2023-03-26 23:24    [W:0.049 / U:0.172 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site