PWMBUS(9)

💅 PWMBUS(9) — like, the pwmbus methods, bestie 🎀

okay so this is pwmbus(9), a section 9 kernel developer's manual page, and it's literally about the PWMBUS methods. if you're a kernel dev who wants their driver to do the pulse-width-modulation thing the generic way, this is your page. pull up a chair 🫶

---

✨ NAME ✨

pwmbus, PWMBUS_CHANNEL_CONFIG, PWMBUS_CHANNEL_COUNT, PWMBUS_CHANNEL_ENABLE, PWMBUS_CHANNEL_GET_CONFIG, PWMBUS_CHANNEL_GET_FLAGS, PWMBUS_CHANNEL_IS_ENABLED, PWMBUS_CHANNEL_SET_FLAGS, PWMBUS_GET_BUS — the PWMBUS methods, periodt 💅

---

🌸 SYNOPSIS 🌸

device pwm
#include <pwmbus_if.h>

int
PWMBUS_CHANNEL_CONFIG(device_t bus, u_int channel, u_int period,
      u_int duty);

int
PWMBUS_CHANNEL_COUNT(device_t bus, u_int *nchannel);

int
PWMBUS_CHANNEL_ENABLE(device_t bus, u_int channel, bool enable);

int
PWMBUS_CHANNEL_GET_CONFIG(device_t bus, u_int channel, u_int *period,
      u_int *duty);

int
PWMBUS_CHANNEL_GET_FLAGS(device_t bus, u_int channel, uint32_t *flags);

int
PWMBUS_CHANNEL_IS_ENABLED(device_t bus, u_int channel, bool *enabled);

int
PWMBUS_CHANNEL_SET_FLAGS(device_t bus, u_int channel, uint32_t flags);

---

🦋 DESCRIPTION 🦋

okay so the big picture: the PWMBUS (that's Pulse-Width Modulation, iykyk) interface lets a device driver register onto a global bus, so that other devices in the kernel can then use them in a generic, uniform way. it's giving "everyone shares the aux" energy. ✨

now for the two arguments you'll see everywhere, so listen up bestie:

• the period argument = the duration, in nanoseconds, of one complete on-off cycle 🔁
• the duty argument = the duration, in nanoseconds, of the on portion of that cycle 💡

some PWM hardware is organized as a single controller with multiple channels, and channel numbers count up from zero (0️⃣, 1️⃣, 2️⃣…). when multiple channels are present, they sometimes share a common clock or other resources — and in those cases, changing the period or duty cycle of any one channel may affect other channels within the hardware that share the same resources. 💀 so like, consult the documentation for the underlying PWM hardware device driver for the details on channels that share resources. no cap, read the docs.

---

👑 INTERFACE 👑

🧚 PWMBUS_CHANNEL_CONFIG(device_t bus, u_int channel, u_int period, u_int duty)

configure the period and duty (both in nanoseconds) in the PWM controller on the bus, for the channel you specified.

returns 0 on success, or EINVAL if the values aren't supported by the controller, or EBUSY if the PWMBUS controller is in use and does not support changing the value on the fly. 😭

🍓 PWMBUS_CHANNEL_COUNT(device_t bus, u_int *nchannel)

get the number of channels supported by the controller. that's it, that's the vibe. 🔢

💜 PWMBUS_CHANNEL_ENABLE(device_t bus, u_int channel, bool enable)

enable the PWM channel. turn it on, bestie. ⚡

🌈 PWMBUS_CHANNEL_GET_CONFIG(device_t bus, u_int channel, u_int *period, u_int *duty)

get the current configuration of the period and duty for the specified channel. a little peek at what's going on in there 👀

⭐ PWMBUS_CHANNEL_GET_FLAGS(device_t bus, u_int channel, uint32_t *flags)

get the current flags for the channel. and here's the cute part: if the driver or controller doesn't support this, a default method returns a flags value of zero. so you always get something back 🫶

🎀 PWMBUS_CHANNEL_IS_ENABLED(device_t bus, u_int channel, bool *enable)

test whether the PWM channel is enabled. vibe check on the channel, basically ✅

🔥 PWMBUS_CHANNEL_SET_FLAGS(device_t bus, u_int channel, uint32_t flags)

set the flags of the channel (such as inverted polarity 🌀). and if the driver or controller doesn't support this, a do-nothing default method is used — so nothing happens, and that's fine, no drama 🙈

---

🧚 HISTORY 🧚

the pwmbus interface first appear in FreeBSD 13.0 ✨ (yes, "appear" — we're keeping the original's exact wording, it's iconic). the pwmbus interface and this manual page were written by Emmanuel Vadot <manu@FreeBSD.org> 👑

---

ok that's the whole page bestie, you ate that 🍽️💅 go forth and modulate those pulses 💖

this cutie came out of the Debian corner of the world, dated March 9, 2021, and it's the PWMBUS(9) page from the Kernel Developer's Manual — mwah, bye! 😘