Re: [PATCH 3/3] Documentation: ABI: sysfs-driver-regulator-output

[Zev Weiss]

Adding Greg re: sysfs ABI design...

On Thu, Aug 31, 2023 at 05:14:10AM PDT, Naresh Solanki wrote:
> Adds sysfs-driver-regulator-output
>
> Signed-off-by: Naresh Solanki <Naresh.Solanki@xxxxxxxxxxxxx>
> ---
> .../ABI/testing/sysfs-driver-regulator-output         | 11 +++++++++++
> 1 file changed, 11 insertions(+)
> create mode 100644 Documentation/ABI/testing/sysfs-driver-regulator-output
>
> diff --git a/Documentation/ABI/testing/sysfs-driver-regulator-output b/Documentation/ABI/testing/sysfs-driver-regulator-output
> new file mode 100644
> index 000000000000..f9b0a8f810fa
> --- /dev/null
> +++ b/Documentation/ABI/testing/sysfs-driver-regulator-output
> @@ -0,0 +1,11 @@
> +What:		/sys/bus/platform/drivers/regulator-output/*/events
> +Date:		August 2023
> +Description:	Provided regulator events.
> +
> +		Read provides various events the regulator associated with the
> +		driver has encountered. All REGULATOR_EVENT_* are
> +		defined in include/uapi/linux/regulator.h
> +
> +		e.g.
> +		cat /sys/bus/platform/drivers/regulator-output/ssb_rssd32/events
> +		0x0

If we really are going to proceed with a "read with side-effects" 
(clear-on-read) design, that should absolutely be loudly and clearly 
documented, since it's very different from how sysfs files typically 
work and hence a somewhat glaring principle-of-least-surprise violation.  
Also, since from the code it looks like it's intended to be used via 
poll(2), that should be described here as well.


Zev