[PATCH] docs: timers: hpet: Modernize file references and document userspace API

[PATCH] docs: timers: hpet: Modernize file references and document userspace API

[Habil Eren Türker]

The current HPET documentation contains outdated 'file:' prefixes for
source tree references, which breaks proper rendering and hyperlink
generation under the modern Sphinx-based documentation ecosystem.

Fix this by modernizing the paths using the standard literal backticks
formatting. Additionally, add a dedicated 'Userspace API and ioctl
Commands' section to clearly document the supported ioctl interfaces
extrapolated from include/uapi/linux/hpet.h and samples/timers/hpet_example.c,
including the layout of struct hpet_info.

Signed-off-by: Habil Eren Türker <habilerenturker@hotmail.com>
---
 Documentation/timers/hpet.rst | 31 +++++++++++++++++++++++++++++--
 1 file changed, 29 insertions(+), 2 deletions(-)

diff --git a/Documentation/timers/hpet.rst b/Documentation/timers/hpet.rst
index c9d05d3ca..e21a6185b 100644
--- a/Documentation/timers/hpet.rst
+++ b/Documentation/timers/hpet.rst
@@ -23,8 +23,35 @@ The driver supports detection of HPET driver allocation and initialization
 of the HPET before the driver module_init routine is called.  This enables
 platform code which uses timer 0 or 1 as the main timer to intercept HPET
 initialization.  An example of this initialization can be found in
-arch/x86/kernel/hpet.c.
+``arch/x86/kernel/hpet.c``.
 
 The driver provides a userspace API which resembles the API found in the
 RTC driver framework.  An example user space program is provided in
-file:samples/timers/hpet_example.c
+``samples/timers/hpet_example.c``
+
+Userspace API and ioctl Commands
+================================
+
+* ``HPET_IE_ON`` / ``HPET_IE_OFF``
+  Enables or disables the interrupt generation for the timer channel.
+
+* ``HPET_INFO``
+  It is used to query the capabilities and current status of the HPET. 
+  When the ioctl call is made, the kernel populates the ``struct hpet_info`` 
+  structure and returns it to userspace:
+
+  .. code-block:: c
+
+     struct hpet_info {
+         unsigned long hi_ireqfreq;	/* Hz */
+         unsigned long hi_flags;	/* information */
+         unsigned short hi_hpet;
+         unsigned short hi_timer;
+     };
+
+* ``HPET_EPI`` / ``HPET_DPI``
+  Enables or disables periodic interrupts. When activated, the timer triggers continuously at the specified frequency.
+
+* ``HPET_IRQFREQ``
+  Sets the interrupt frequency for the periodic timer. 
+  This request takes an unsigned long argument specifying the desired frequency in Hz.
-- 
2.47.3

Re: [PATCH] docs: timers: hpet: Modernize file references and document userspace API

[Jonathan Corbet]

"Habil Eren Türker" <habilerenturker@gmail.com> writes:

> The current HPET documentation contains outdated 'file:' prefixes for
> source tree references, which breaks proper rendering and hyperlink
> generation under the modern Sphinx-based documentation ecosystem.
>
> Fix this by modernizing the paths using the standard literal backticks
> formatting. Additionally, add a dedicated 'Userspace API and ioctl
> Commands' section to clearly document the supported ioctl interfaces
> extrapolated from include/uapi/linux/hpet.h and samples/timers/hpet_example.c

"Additionally" is a clue that you should be dividing this work into two
separate patches.

,
> including the layout of struct hpet_info.
>
> Signed-off-by: Habil Eren Türker <habilerenturker@hotmail.com>
> ---
>  Documentation/timers/hpet.rst | 31 +++++++++++++++++++++++++++++--
>  1 file changed, 29 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/timers/hpet.rst b/Documentation/timers/hpet.rst
> index c9d05d3ca..e21a6185b 100644
> --- a/Documentation/timers/hpet.rst
> +++ b/Documentation/timers/hpet.rst
> @@ -23,8 +23,35 @@ The driver supports detection of HPET driver allocation and initialization
>  of the HPET before the driver module_init routine is called.  This enables
>  platform code which uses timer 0 or 1 as the main timer to intercept HPET
>  initialization.  An example of this initialization can be found in
> -arch/x86/kernel/hpet.c.
> +``arch/x86/kernel/hpet.c``.
>  
>  The driver provides a userspace API which resembles the API found in the
>  RTC driver framework.  An example user space program is provided in
> -file:samples/timers/hpet_example.c
> +``samples/timers/hpet_example.c``
> +
> +Userspace API and ioctl Commands
> +================================
> +
> +* ``HPET_IE_ON`` / ``HPET_IE_OFF``
> +  Enables or disables the interrupt generation for the timer channel.
> +
> +* ``HPET_INFO``
> +  It is used to query the capabilities and current status of the HPET. 
> +  When the ioctl call is made, the kernel populates the ``struct hpet_info`` 
> +  structure and returns it to userspace:
> +
> +  .. code-block:: c
> +
> +     struct hpet_info {
> +         unsigned long hi_ireqfreq;	/* Hz */
> +         unsigned long hi_flags;	/* information */
> +         unsigned short hi_hpet;
> +         unsigned short hi_timer;
> +     };
> +
> +* ``HPET_EPI`` / ``HPET_DPI``
> +  Enables or disables periodic interrupts. When activated, the timer triggers continuously at the specified frequency.

Please keep text files to less than 80 columns.

Thanks,

jon