This patch adds some examples about how to register a new PPS
generator in the system, and how to manage it.

Signed-off-by: Rodolfo Giometti <giometti@enneenne.com>
---
 Documentation/driver-api/pps.rst | 40 ++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/Documentation/driver-api/pps.rst b/Documentation/driver-api/pps.rst
index 78dded03e5d8..dffa06ed919f 100644
--- a/Documentation/driver-api/pps.rst
+++ b/Documentation/driver-api/pps.rst
@@ -202,6 +202,46 @@ Sometimes one needs to be able not only to catch PPS signals but to produce
 them also. For example, running a distributed simulation, which requires
 computers' clock to be synchronized very tightly.
 
+To do so the class pps-gen has been added. PPS generators can be
+registered in the kernel by defining a struct pps_gen_source_info as
+follows::
+
+    static struct pps_gen_source_info pps_gen_dummy_info = {
+            .name                   = "dummy",
+            .use_system_clock       = true,
+            .get_time               = pps_gen_dummy_get_time,
+            .enable                 = pps_gen_dummy_enable,
+    };
+
+Where the use_system_clock states if the generator uses the system
+clock to generate its pulses, or from a peripheral device
+clock. Method get_time() is used to query the time stored into the
+generator clock, while the method enable() is used to enable or
+disable the PPS pulse generation.
+
+Then calling the function pps_gen_register_source() in your
+initialization routine as follows creates a new generator in the
+system::
+
+    pps_gen = pps_gen_register_source(&pps_gen_dummy_info);
+
+Generators SYSFS support
+------------------------
+
+If the SYSFS filesystem is enabled in the kernel it provides a new class::
+
+    $ ls /sys/class/pps-gen/
+    pps-gen0/  pps-gen1/  pps-gen2/
+
+Every directory is the ID of a PPS generator defined in the system and
+inside you find several files::
+
+    $ ls -F /sys/class/pps-gen/pps-gen0/
+    dev  enable  name  power/  subsystem@  system  time  uevent
+
+To enable the PPS signal generation you can use the command below::
+
+    $ echo 1 > /sys/class/pps-gen/pps-gen0/enable
 
 Parallel port generator
 ------------------------
-- 
2.34.1

On Thu, Oct 31, 2024 at 05:35:07PM +0100, Rodolfo Giometti wrote:
> +Every directory is the ID of a PPS generator defined in the system and
> +inside you find several files::
  "inside of it ..."
> +
> +    $ ls -F /sys/class/pps-gen/pps-gen0/
> +    dev  enable  name  power/  subsystem@  system  time  uevent
> +
 
Thanks.

-- 
An old man doll... just what I always wanted! - Clara

On 10/31/24 9:35 AM, Rodolfo Giometti wrote:
> This patch adds some examples about how to register a new PPS
> generator in the system, and how to manage it.
> 
> Signed-off-by: Rodolfo Giometti <giometti@enneenne.com>
> ---
>  Documentation/driver-api/pps.rst | 40 ++++++++++++++++++++++++++++++++
>  1 file changed, 40 insertions(+)
> 
> diff --git a/Documentation/driver-api/pps.rst b/Documentation/driver-api/pps.rst
> index 78dded03e5d8..dffa06ed919f 100644
> --- a/Documentation/driver-api/pps.rst
> +++ b/Documentation/driver-api/pps.rst
> @@ -202,6 +202,46 @@ Sometimes one needs to be able not only to catch PPS signals but to produce
>  them also. For example, running a distributed simulation, which requires
>  computers' clock to be synchronized very tightly.
>  
> +To do so the class pps-gen has been added. PPS generators can be
> +registered in the kernel by defining a struct pps_gen_source_info as
> +follows::
> +
> +    static struct pps_gen_source_info pps_gen_dummy_info = {
> +            .name                   = "dummy",
> +            .use_system_clock       = true,
> +            .get_time               = pps_gen_dummy_get_time,
> +            .enable                 = pps_gen_dummy_enable,
> +    };
> +
> +Where the use_system_clock states if the generator uses the system
> +clock to generate its pulses, or from a peripheral device

                                 or they are from a peripheral device

> +clock. Method get_time() is used to query the time stored into the
> +generator clock, while the method enable() is used to enable or
> +disable the PPS pulse generation.
> +
> +Then calling the function pps_gen_register_source() in your
> +initialization routine as follows creates a new generator in the
> +system::
> +
> +    pps_gen = pps_gen_register_source(&pps_gen_dummy_info);
> +
> +Generators SYSFS support
> +------------------------
> +
> +If the SYSFS filesystem is enabled in the kernel it provides a new class::
> +
> +    $ ls /sys/class/pps-gen/
> +    pps-gen0/  pps-gen1/  pps-gen2/
> +
> +Every directory is the ID of a PPS generator defined in the system and
> +inside you find several files::
> +
> +    $ ls -F /sys/class/pps-gen/pps-gen0/
> +    dev  enable  name  power/  subsystem@  system  time  uevent
> +
> +To enable the PPS signal generation you can use the command below::
> +
> +    $ echo 1 > /sys/class/pps-gen/pps-gen0/enable
>  
>  Parallel port generator
>  ------------------------

-- 
~Randy