[PATCH v2 0/2] docs: timers: hpet: Modernize and document API

[PATCH v2 0/2] docs: timers: hpet: Modernize and document API

[Habil Eren Türker]

This series addresses the feedback from Jonathan Corbet on the initial 
submission. The work has been split into two separate patches, and the 
line length has been restricted to under 80 columns.

Habil Eren Türker (2):
  docs: timers: hpet: Modernize file references
  docs: timers: hpet: Document userspace API and ioctl commands

 Documentation/timers/hpet.rst | 32 ++++++++++++++++++++++++++++++--
 1 file changed, 30 insertions(+), 2 deletions(-)

-- 
2.47.3

[PATCH v2 1/2] [PATCH v2 1/2] docs: timers: hpet: Modernize file references

[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.

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

diff --git a/Documentation/timers/hpet.rst b/Documentation/timers/hpet.rst
index c9d05d3ca..fe02bfd5d 100644
--- a/Documentation/timers/hpet.rst
+++ b/Documentation/timers/hpet.rst
@@ -23,8 +23,8 @@ 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``
\ No newline at end of file
-- 
2.47.3

[PATCH v2 2/2] [PATCH v2 2/2] docs: timers: hpet: Document userspace API and ioctl commands

[Habil Eren Türker]

Add a dedicated 'Userspace API and ioctl Commands' section to clearly
document the supported ioctl interfaces extrapolated from
include/uapi/linux/hpet.h, including the layout of struct hpet_info.

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

diff --git a/Documentation/timers/hpet.rst b/Documentation/timers/hpet.rst
index fe02bfd5d..cc9fb3e37 100644
--- a/Documentation/timers/hpet.rst
+++ b/Documentation/timers/hpet.rst
@@ -27,4 +27,32 @@ initialization.  An example of this initialization can be found in
 
 The driver provides a userspace API which resembles the API found in the
 RTC driver framework.  An example user space program is provided in
-``samples/timers/hpet_example.c``
\ No newline at end of file
+``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 v2 1/2] [PATCH v2 1/2] docs: timers: hpet: Modernize file references

[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.
>
> Signed-off-by: Habil Eren Türker <habilerenturker@hotmail.com>
> ---
>  Documentation/timers/hpet.rst | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/timers/hpet.rst b/Documentation/timers/hpet.rst
> index c9d05d3ca..fe02bfd5d 100644
> --- a/Documentation/timers/hpet.rst
> +++ b/Documentation/timers/hpet.rst
> @@ -23,8 +23,8 @@ 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``
> \ No newline at end of file

That last line is something you should really have fixed before sending
this patch.

Thanks,

jon

Re: [PATCH v2 1/2] [PATCH v2 1/2] docs: timers: hpet: Modernize file references

[Jonathan Corbet]

Jonathan Corbet <corbet@lwn.net> writes:

> "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.
>>
>> Signed-off-by: Habil Eren Türker <habilerenturker@hotmail.com>
>> ---
>>  Documentation/timers/hpet.rst | 4 ++--
>>  1 file changed, 2 insertions(+), 2 deletions(-)
>>
>> diff --git a/Documentation/timers/hpet.rst b/Documentation/timers/hpet.rst
>> index c9d05d3ca..fe02bfd5d 100644
>> --- a/Documentation/timers/hpet.rst
>> +++ b/Documentation/timers/hpet.rst
>> @@ -23,8 +23,8 @@ 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``
>> \ No newline at end of file
>
> That last line is something you should really have fixed before sending
> this patch.

I guess the next patch does fix it, so no need to resend for that.

One other question: did you write these patches yourself, or was there
LLM assistance involved?  In the latter case, they need Assisted-by
tags.

Thanks,

jon

Re: [PATCH v2 1/2] [PATCH v2 1/2] docs: timers: hpet: Modernize file references

[Habil Eren Türker]

Hi Jonathan,

Thanks for the note.
 
Yes, I used an LLM assistant, and I will resubmit 
with the proper "Assisted-by" tags.

To be more specific: the LLM pointed out that the 'file:' prefix is ​​
deprecated and suggested using backticks instead. 
It also helped correct some typos in the commit message and documentation 
text.

The rest of the work - identifying the issue, researching, verifying, 
and resolving it - was entirely my own.

Sorry for the noise; I will send v3 with the correct tags shortly.

Regards,
Türker

[PATCH v3 0/2] docs: timers: hpet: Modernize and document API

[Habil Eren Türker]

This series updates the HPET (High Precision Event Timer) documentation
by updating outdated file paths and documenting the userspace API, including
the available ioctl commands.

---

v2 -> v3:
- Add Assisted-by tags to individual patches for LLM assistance.
- Remove stray [PATCH v2 x/2] prefixes from commit subjects.
- Fix a missing newline warning.

v1 -> v2:
- Split the original single patch into a two-patch series.
- Keep the text files less than 80 columns.

Habil Eren Türker (2):
  docs: timers: hpet: Modernize file references
  docs: timers: hpet: Document userspace API and ioctl commands

 Documentation/timers/hpet.rst | 33 +++++++++++++++++++++++++++++++--
 1 file changed, 31 insertions(+), 2 deletions(-)

-- 
2.47.3

[PATCH v3 1/2] docs: timers: hpet: Modernize file references

[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.

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

diff --git a/Documentation/timers/hpet.rst b/Documentation/timers/hpet.rst
index c9d05d3ca..8bb51d971 100644
--- a/Documentation/timers/hpet.rst
+++ b/Documentation/timers/hpet.rst
@@ -23,8 +23,8 @@ 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``
-- 
2.47.3

[PATCH v3 2/2] docs: timers: hpet: Document userspace API and ioctl commands

[Habil Eren Türker]

Add a dedicated 'Userspace API and ioctl Commands' section to clearly
document the supported ioctl interfaces extrapolated from
include/uapi/linux/hpet.h, including the layout of struct hpet_info.

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

diff --git a/Documentation/timers/hpet.rst b/Documentation/timers/hpet.rst
index 8bb51d971..007e906ae 100644
--- a/Documentation/timers/hpet.rst
+++ b/Documentation/timers/hpet.rst
@@ -28,3 +28,32 @@ initialization.  An example of this initialization can be found in
 The driver provides a userspace API which resembles the API found in the
 RTC driver framework.  An example user space program is provided in
 ``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