[v1] Add PPS generators

[V1 4/4] Documentation ABI: add PPS generators documentation

Posted by Rodolfo Giometti 1 month, 1 week ago

This patch adds the documentation for the ABI between the Linux kernel
and userspace regarding the PPS generators.

Signed-off-by: Rodolfo Giometti <giometti@enneenne.com>
---
 Documentation/ABI/testing/sysfs-pps-gen | 44 +++++++++++++++++++++++++
 1 file changed, 44 insertions(+)
 create mode 100644 Documentation/ABI/testing/sysfs-pps-gen

diff --git a/Documentation/ABI/testing/sysfs-pps-gen b/Documentation/ABI/testing/sysfs-pps-gen
new file mode 100644
index 000000000000..427ba985f413
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-pps-gen
@@ -0,0 +1,44 @@
+What:		/sys/class/pps-gen/
+Date:		October 2024
+Contact:	Rodolfo Giometti <giometti@enneenne.com>
+Description:
+		The /sys/class/pps-gen/ directory will contain files and
+		directories that will provide a unified interface to
+		the PPS generators.
+
+What:		/sys/class/pps-gen/pps-genX/
+Date:		October 2024
+Contact:	Rodolfo Giometti <giometti@enneenne.com>
+Description:
+		The /sys/class/pps-gen/pps-genX/ directory is related to X-th
+		PPS generator into the system. Each directory will
+		contain files to manage and control its PPS generator.
+
+What:		/sys/class/pps-gen/pps-genX/enable
+Date:		October 2024
+Contact:	Rodolfo Giometti <giometti@enneenne.com>
+Description:
+		This write-only file enables or disables generation of the
+		PPS signal.
+
+What:		/sys/class/pps-gen/pps-genX/name
+Date:		October 2024
+Contact:	Rodolfo Giometti <giometti@enneenne.com>
+Description:
+		This read-only file reports the name of the X-th generator.
+
+What:		/sys/class/pps-gen/pps-genX/system
+Date:		October 2024
+Contact:	Rodolfo Giometti <giometti@enneenne.com>
+Description:
+		This read-only file returns "1" if the generator takes the
+		timing from the system clock, while it returns "0" if not
+		(i.e. from a peripheral device clock).
+
+What:		/sys/class/pps-gen/pps-genX/time
+Date:		October 2024
+Contact:	Rodolfo Giometti <giometti@enneenne.com>
+Description:
+		This read-only file contains the current time stored into the
+		generator clock as two integers representing the current time
+		seconds and nanoseconds.
-- 
2.34.1

Re: [V1 4/4] Documentation ABI: add PPS generators documentation

Posted by Randy Dunlap 1 month ago


On 10/18/24 7:39 AM, Rodolfo Giometti wrote:
> This patch adds the documentation for the ABI between the Linux kernel
> and userspace regarding the PPS generators.
> 
> Signed-off-by: Rodolfo Giometti <giometti@enneenne.com>
> ---
>  Documentation/ABI/testing/sysfs-pps-gen | 44 +++++++++++++++++++++++++
>  1 file changed, 44 insertions(+)
>  create mode 100644 Documentation/ABI/testing/sysfs-pps-gen
> 

The files "enable", "name", "system", and "time" descriptions are written in
present tense. Preferably change the descriptions for "pps-gen" and "pps-genX"
to present tense also.


> diff --git a/Documentation/ABI/testing/sysfs-pps-gen b/Documentation/ABI/testing/sysfs-pps-gen
> new file mode 100644
> index 000000000000..427ba985f413
> --- /dev/null
> +++ b/Documentation/ABI/testing/sysfs-pps-gen
> @@ -0,0 +1,44 @@
> +What:		/sys/class/pps-gen/
> +Date:		October 2024
> +Contact:	Rodolfo Giometti <giometti@enneenne.com>
> +Description:
> +		The /sys/class/pps-gen/ directory will contain files and

		                                  contains file and

> +		directories that will provide a unified interface to

		            that provide a

> +		the PPS generators.
> +
> +What:		/sys/class/pps-gen/pps-genX/
> +Date:		October 2024
> +Contact:	Rodolfo Giometti <giometti@enneenne.com>
> +Description:
> +		The /sys/class/pps-gen/pps-genX/ directory is related to X-th
> +		PPS generator into the system. Each directory will

		              in the system.
		                               Each directory

> +		contain files to manage and control its PPS generator.

		contains files

> +
> +What:		/sys/class/pps-gen/pps-genX/enable
> +Date:		October 2024
> +Contact:	Rodolfo Giometti <giometti@enneenne.com>
> +Description:
> +		This write-only file enables or disables generation of the
> +		PPS signal.
> +
> +What:		/sys/class/pps-gen/pps-genX/name
> +Date:		October 2024
> +Contact:	Rodolfo Giometti <giometti@enneenne.com>
> +Description:
> +		This read-only file reports the name of the X-th generator.
> +
> +What:		/sys/class/pps-gen/pps-genX/system
> +Date:		October 2024
> +Contact:	Rodolfo Giometti <giometti@enneenne.com>
> +Description:
> +		This read-only file returns "1" if the generator takes the
> +		timing from the system clock, while it returns "0" if not
> +		(i.e. from a peripheral device clock).
> +
> +What:		/sys/class/pps-gen/pps-genX/time
> +Date:		October 2024
> +Contact:	Rodolfo Giometti <giometti@enneenne.com>
> +Description:
> +		This read-only file contains the current time stored into the
> +		generator clock as two integers representing the current time
> +		seconds and nanoseconds.

-- 
~Randy

Re: [V1 4/4] Documentation ABI: add PPS generators documentation

Posted by Andy Shevchenko 1 month, 1 week ago

On Fri, Oct 18, 2024 at 04:39:15PM +0200, Rodolfo Giometti wrote:
> This patch adds the documentation for the ABI between the Linux kernel
> and userspace regarding the PPS generators.

...

> +Date:		October 2024

The rule of thumb is to have the date of the estimated kernel release where
this ABI will be available from.

Citing our internal recommendations about this:
"The field Date, usually in the format MONTH YEAR, should be aligned with the
release date of the first release of the kernel where this entry will appear.
The release date can be predicted using the prediction machine, AKA Kernel
crystal ball."

The prediction machine URL: https://hansen.beer/~dave/phb/

-- 
With Best Regards,
Andy Shevchenko