REGULATOR(9)

Hey bestie! 💖 Welcome to REGULATOR(9) — that's the Kernel Developer's Manual page for the regulator framework. It's giving power management main character energy, and honestly? You're gonna slay this. Let me walk you through it. 🎀

---

✨ NAME ✨

Okay so this page covers the whole regulator squad: regulator, regulator_get_by_name, regulator_get_by_id, regulator_release, regulator_get_name, regulator_enable, regulator_disable, regulator_stop, regulator_status, regulator_get_voltage, regulator_set_voltage, regulator_check_voltage, regulator_get_by_ofw_property — and these are literally the regulator methods. The whole crew. No cap. 💅

---

💫 SYNOPSIS 💫

Bestie, here's the receipts. You need device regulator and this include:

device regulator
#include <dev/extres/regulator/regulator.h>

And here are all the function signatures, exactly as they appear:

int
regulator_get_by_name(device_t cdev, const char *name,
      regulator_t *regulator);

int
regulator_get_by_id(device_t cdev, device_t pdev, intptr_t id,
      regulator_t *regulator);

int
regulator_release(regulator_t regulator);

int
regulator_get_name(regulator_t regulator);

int
regulator_enable(regulator_t reg);

int
regulator_disable(regulator_t reg);

int
regulator_stop(regulator_t reg);

int
regulator_status(regulator_t reg, int *status);

int
regulator_get_voltage(regulator_t reg, int *uvolt);

int
regulator_set_voltage(regulator_t reg, int min_uvolt, int max_uvolt);

int
regulator_check_voltage(regulator_t reg, int uvolt);

int
regulator_get_by_ofw_property(device_t dev, phandle_t node, char *name,
      regulator_t *reg);

---

🌸 DESCRIPTION 🌸

The regulator framework is lowkey the GOAT: it lets drivers enable, disable, and change regulator voltage. It's the whole vibe for power management. ⚡✨

---

🫶 RETURN VALUES 🫶

Okay so here's the tea: all these functions return 0 on success — or ENODEV if the regulator (or one of its parents) was not found. That's the standard return drama. Don't forget it. 😭

---

✨ INTERFACE ✨

Alright bestie, let's go function by function. Every detail is about to be served, periodt.

• regulator_get_by_name(device_t cdev, const char *name, regulator_t *regulator) — Resolve a regulator based on its name. All regulator names are unique (slay for no duplicates 🎀). This will also increment the refcount on the regulator — so heads up, you're holding a reference. 💅
• regulator_get_by_id(device_t cdev, device_t pdev, intptr_t id, regulator_t *regulator) — Resolve a regulator based on its id. All regulator ids are unique, too. This will also increment the refcount on the regulator. Same energy as above. 🔥
• regulator_get_by_ofw_property(device_t dev, phandle_t node, char *name, regulator_t *reg) — Resolve a regulator based on the fdt property named name. If node is 0, then the function will get the ofw node itself. This will also increment the refcount on the regulator. It returns 0 on success or ENOENT if the ofw property does not exist. So if it's missing, that's a ENOENT moment. 🙈
• regulator_release(regulator_t regulator) — This disables the regulator, decrements the refcount on it, and frees the regulator variable passed. So like, it's the cleanup era. You're done with it, and it's done with you. 🦋
• regulator_get_name(regulator_t regulator) — Returns the name of the regulator. All regulator names are unique. Literally every single one. 🌈
• regulator_enable(regulator_t reg) — Enable the regulator. If the regulator supports a voltage range, the one configured in the hardware will be the output voltage. If the regulator was already enabled by another driver, this simply increments the enable counter. So no drama — just counting vibes. ⭐
• regulator_disable(regulator_t reg) — Disable the regulator. If the regulator was also enabled by another driver, this simply decrements the enable counter. But bestie, listen: if the regulator was not previously enabled, we will kassert. And a kassert is not a vibe — it's a kernel assertion failure. So don't do that. 😭💀
• regulator_stop(regulator_t reg) — Disable the regulator in hardware. This ensures the regulator is disabled even if it was enabled by the bootloader. This should not be called on a regulator that has previously been enabled by a driver. So pay attention. 👀 Returns 0 on success or EBUSY if another consumer enabled it.
• regulator_status(regulator_t reg, int *status) — Get the hardware status of the regulator. status will contain a bit mask with these possible values:
  • REGULATOR_STATUS_ENABLED — The regulator is enabled. ✅
  • REGULATOR_STATUS_OVERCURRENT — The hardware reports that too much current is being drawn. 🚨
• regulator_get_voltage(regulator_t reg, int *uvolt) — Get the current voltage set for the regulator in microvolts. Microvolts, bestie. Tiny units. 🧚
• regulator_set_voltage(regulator_t reg, int min_uvolt, int max_uvolt) — Change the voltage for the regulator. If a range is acceptable by the hardware or driver, different values can be provided as min and max. Returns 0 on success or ERANGE if the regulator doesn't support this voltage range. So if it's out of range, that's an ERANGE situation. 💜
• regulator_check_voltage(regulator_t reg, int uvolt) — Checks if the regulator supports the given voltage. Returns 0 on success or ERANGE if the regulator doesn't support this voltage range. Just a little vibe check before you commit. ✨

---

🌈 HISTORY 🌈

The regulator framework first appeared in FreeBSD 12.0. The regulator framework was written by Michal Meloun <mmel@FreeBSD.org>. The regulator manual page was written by Emmanuel Vadot <manu@FreeBSD.org>. Shoutout to them for the lore. 👑

---

This page was brought to you by the Debian squad, dated June 14, 2021. REGULATOR(9) out! 🎀💖