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

[Jonathan Corbet <corbet@lwn.net>]

"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