[PATCH] regulator: consumer.rst: document bulk operations

[PATCH] regulator: consumer.rst: document bulk operations

[Javier Carrasco]

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>
---
 Documentation/power/regulator/consumer.rst | 30 ++++++++++++++++++++++++++----
 1 file changed, 26 insertions(+), 4 deletions(-)

diff --git a/Documentation/power/regulator/consumer.rst b/Documentation/power/regulator/consumer.rst
index 9d2416f63f6e..c01675b25a90 100644
--- 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)
 =======================================================
 

---
base-commit: 8f5ae30d69d7543eee0d70083daf4de8fe15d585
change-id: 20250819-reg_consumer_doc-bbb3d2a7eb14

Best regards,
--  
Javier Carrasco <javier.carrasco.cruz@gmail.com>

Re: [PATCH] regulator: consumer.rst: document bulk operations

[Mark Brown]

[-- Attachment #1: Type: text/plain, Size: 618 bytes --]

On Tue, Aug 19, 2025 at 12:25:43PM +0800, Javier Carrasco wrote:
> 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>
> ---

You need to put the signoff before the ---, anything after the --- will
get deleted when applying.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: [PATCH] regulator: consumer.rst: document bulk operations

[Javier Carrasco]

On Tue Aug 19, 2025 at 11:52 PM CST, Mark Brown wrote:
> On Tue, Aug 19, 2025 at 12:25:43PM +0800, Javier Carrasco wrote:
>> 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>
>> ---
>
> You need to put the signoff before the ---, anything after the --- will
> get deleted when applying.

Sorry about that, I wrote a cover letter that I later removed, and b4
ended up adding the ---, which I missed before sending upstream.

Thank you for applying the patch, I am planning to update the
documentation of the regulator API when I have some time, and I will
make sure that the patches are properly formatted.

Best regards,
Javier Carrasco

Re: [PATCH] regulator: consumer.rst: document bulk operations

[Mark Brown]

On Tue, 19 Aug 2025 12:25:43 +0800, Javier Carrasco wrote:
> 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.
> 
> [...]

Applied to

   https://git.kernel.org/pub/scm/linux/kernel/git/broonie/regulator.git for-next

Thanks!

[1/1] regulator: consumer.rst: document bulk operations
      commit: ec0be3cdf40b5302248f3fb27a911cc630e8b855

All being well this means that it will be integrated into the linux-next
tree (usually sometime in the next 24 hours) and sent to Linus during
the next merge window (or sooner if it is a bug fix), however if
problems are discovered then the patch may be dropped or reverted.

You may get further e-mails resulting from automated or manual testing
and review of the tree, please engage with people reporting problems and
send followup patches addressing any issues that are reported if needed.

If any updates are required or you are submitting further changes they
should be sent as incremental updates against current git, existing
patches will not be replaced.

Please add any relevant lists and maintainers to the CCs when replying
to this mail.

Thanks,
Mark