drivers/power: Describe the regulators through procfs.

The regulator framework has no way out to userspace: consumers reach a
rail by name from inside the kernel, which is the right interface for
controlling one, but it leaves a board with regulators offering no way
to see what they are doing, and a newly written regulator driver cannot
be looked at without writing a consumer for it first.

Adds /proc/regulator, behind REGULATOR_PROCFS, listing every registered
regulator: its present voltage, the range it will accept, whether it is
enabled, how many consumers hold and enable it, its supply, and whether
it is always on or expected on at boot.  Lines carry the same key:value
tokens in the same order, so the file is machine parseable.  The last
two are worth reading beside the consumer count, since a rail enabled
with no consumers is expected rather than suspect when either is set.

A part usually measures more than the framework has fields for, so
struct regulator_ops_s gains an optional describe method: it writes
key:value text and the renderer appends it to that rail's line.  This is
how a driver reports what only it knows, an input voltage, an output
current, a temperature or a fault word, without the framework growing a
field per part or the driver growing procfs code of its own.  It is
called with the list mutex held and never from interrupt context, so
reading the part over a bus is allowed.

The voltage and the enabled state are read back from the hardware rather
than recalled, so a rail the boot loader set and nothing has touched
since reads as it actually is.  Both calls can fail, and a failure
reports - rather than an errno formatted as a voltage or a rail that
looks switched on.

Reading the hardware is also why this takes the list mutex directly
rather than calling regulator_list_lock(), which additionally disables
interrupts so that callers in interrupt or idle context are safe.
Asking a regulator on a bus what it is doing means a transfer, and a
transfer waits; a task reading a file can afford to wait and an
interrupt handler cannot.

procfs_register() appends without checking for duplicates, so the entry
is claimed once for the lifetime of the system rather than whenever the
list is empty.  It also needs FS_PROCFS_REGISTER, which the option now
depends on rather than only FS_PROCFS.

Documents the framework, which had no page at all: the consumer
interface and what counted enables mean, what a driver supplies, and the
new entry.

The entry is read only.  What voltage a rail may be is knowledge its
consumers hold, and arranging the order between them is what the
framework is for, so moving one from a shell would step around the part
that matters.

Assisted-by: Claude:claude-opus-5
Signed-off-by: Justin Hammond <justin@dynam.ac>

include/nuttx/power/regulator.h

@@ -93,6 +93,24 @@ struct regulator_ops_s
                                enum regulator_mode_e mode);
   CODE int (*set_suspend_voltage)(FAR struct regulator_dev_s *, int uv);
   CODE int (*resume)(FAR struct regulator_dev_s *rdev);
+
+  /* Report what this regulator can say about itself that the upper half
+   * has no field for: what a particular part measures or latches, such as
+   * its input voltage, output current, temperature or fault status.
+   *
+   * Optional.  A regulator whose driver omits it is still listed with
+   * everything the upper half knows: its voltage, its range, whether it
+   * is enabled and how many consumers hold it.
+   *
+   * Write at most len bytes into extra as further key:value fields, in
+   * the form the renderer uses, and return OK.  The renderer owns the
+   * line and appends this to it, so a driver needs no procfs knowledge
+   * of its own.  Called with the framework's list lock held and not from
+   * interrupt context, so reading a part over a bus is allowed.
+   */
+
+  CODE int (*describe)(FAR struct regulator_dev_s *rdev, FAR char *extra,
+                       size_t len);
 };
 
 /* This structure describes the regulators capabilities */