regulator: consumer.rst: document bulk operations

The current consumer documentation does not include bulk operations,
providing an example of how to acquire multiple regulators by calling
regulator_get() multiple times. That solution is valid and slightly
simpler for a small amount of regulators, but it does not scale well.

Document the bulk operations to get, enable and disable regulators.

Signed-off-by: Javier Carrasco <javier.carrasco.cruz@gmail.com>
Link: https://patch.msgid.link/20250819-reg_consumer_doc-v1-1-b631fc0d35a3@gmail.com
Signed-off-by: Mark Brown <broonie@kernel.org>

diff --git a/Documentation/power/regulator/consumer.rst b/Documentation/power/regulator/consumer.rst
index 9d2416f63f6e36ff47466a072a4dd101275f3983..c01675b25a901eab6bd592dd072e50d4039d43e5 100644 (file)
--- a/Documentation/power/regulator/consumer.rst
+++ b/Documentation/power/regulator/consumer.rst
@@ -23,10 +23,18 @@ To release the regulator the consumer driver should call ::
        regulator_put(regulator);
 
 Consumers can be supplied by more than one regulator e.g. codec consumer with
-analog and digital supplies ::
+analog and digital supplies by means of bulk operations ::
+
+       struct regulator_bulk_data supplies[2];
+
+       supplies[0].supply = "Vcc"; /* digital core */
+       supplies[1].supply = "Avdd"; /* analog */
+
+       ret = regulator_bulk_get(dev, ARRAY_SIZE(supplies), supplies);
+
+       // convenience helper to call regulator_put() on multiple regulators
+       regulator_bulk_free(ARRAY_SIZE(supplies), supplies);
 
-       digital = regulator_get(dev, "Vcc");  /* digital core */
-       analog = regulator_get(dev, "Avdd");  /* analog */
 
 The regulator access functions regulator_get() and regulator_put() will
 usually be called in your device drivers probe() and remove() respectively.
@@ -51,11 +59,21 @@ A consumer can determine if a regulator is enabled by calling::
 
 This will return > zero when the regulator is enabled.
 
+A set of regulators can be enabled with a single bulk operation ::
+
+       int regulator_bulk_enable(int num_consumers,
+                                 struct regulator_bulk_data *consumers);
+
 
 A consumer can disable its supply when no longer needed by calling::
 
        int regulator_disable(regulator);
 
+Or a number of them ::
+
+       int regulator_bulk_disable(int num_consumers,
+                                  struct regulator_bulk_data *consumers);
+
 NOTE:
   This may not disable the supply if it's shared with other consumers. The
   regulator will only be disabled when the enabled reference count is zero.
@@ -64,11 +82,15 @@ Finally, a regulator can be forcefully disabled in the case of an emergency::
 
        int regulator_force_disable(regulator);
 
+This operation is also supported for multiple regulators ::
+
+       int regulator_bulk_force_disable(int num_consumers,
+                                        struct regulator_bulk_data *consumers);
+
 NOTE:
   this will immediately and forcefully shutdown the regulator output. All
   consumers will be powered off.
 
-
 3. Regulator Voltage Control & Status (dynamic drivers)
 =======================================================