PWMC(4)

📦 version 15.1, in freebsd 14.5, freebsd 15.1, nixpkgs unstable

💖 PWMC(4) — the PWM (Pulse Width Modulation) control device driver, bestie edition 💖

okay so you want to talk to PWM hardware? say less. this is your manual page, and we're gonna make it make sense. no cap, it's giving "low-level but iconic" vibes 💅

✨ SYNOPSIS ✨

bestie, let's get this driver into your kernel 🚀. drop these lines in your kernel configuration file:

device pwmbus
device pwmc

alternatively, if you're a "load it as a module at boot time" kinda girlie, put this line in loader.conf(5):

pwmc_load="YES"

slay. now the driver is ready to vibe check your PWM channels 🎀

🌸 DESCRIPTION 🌸

so the pwmc driver gives you device-control access to a channel of PWM hardware. each instance of a pwmc device is associated with a single PWM output channel. one channel, one instance. periodt 💜

here's the tea though: some PWM hardware is organized with multiple channels sharing a common clock or other resources 😭. in those cases, a separate pwmc instance will exist for each channel, but changing the period or duty cycle of any one channel may affect other channels within the hardware that share the same resources. so like... be careful, bestie. consult the documentation for the underlying PWM hardware device driver for deets on channels that share resources. iykyk 🫶

an instance of pwmc creates a character device named /dev/pwm/pwmcX.Y where X is a sequential number assigned to each PWM hardware controller as it's discovered by the system, and Y is the channel number within that hardware controller. the driver can be configured to create aliases that point to the pwmcX.Y entries — in effect creating named channels. cute, right? 🎀

the pwmc driver provides control of a PWM channel with the following ioctl(2) calls and data structures, defined in <dev/pwm/pwmc.h>:

  • PWMGETSTATE (struct pwm_state) — retrieve the current state of the channel. it's giving "status check" 👀
  • PWMSETSTATE (struct pwm_state) — set the current state of the channel. ⚠️ all parameters are updated on every call. to change just one of the values, use PWMGETSTATE to get the current state and then submit the same data back with just the appropriate value changed. don't skip this step bestie i'm begging 😭

the pwm_state structure is defined as follows:

struct pwm_state {
        u_int           period;
        u_int           duty;
        uint32_t        flags;
        bool            enable;
};
  • period — the duration, in nanoseconds, of one complete on-off cycle. the whole vibe from start to finish ⭐
  • duty — the duration, in nanoseconds, of the on portion of one cycle. the part where the lights are literally on 💡
  • flags — flags that affect the output signal can be bitwise-ORed together. the following flags are currently defined:
    • PWM_POLARITY_INVERTED — invert the signal polarity. flip it, reverse it, make it yours 🔄
  • enable — false to disable the output signal or true to enable it. on or off, no in-between 💅

🦋 HINTS CONFIGURATION 🦋

on a device.hints(5) based system, such as MIPS, these values are configurable for pwmc:

  • hint.pwmc.%d.at — the pwmbus instance the pwmc instance is attached to. the "where you at" of it all 📍
  • hint.pwmc.%d.channel — the hardware channel number the instance is attached to. channel numbers count up from zero. zero, one, two... you get it 💜
  • hint.pwmc.%d.label — if this optional hint is set, the driver creates an alias in /dev/pwm with the given name, which points to the instance. a little nickname for your channel 🎀

🌈 FDT CONFIGURATION 🌈

on an fdt(4) based system, a pwmc device is described with a child node of the pwm hardware controller node. when the hardware supports multiple channels within the controller, it's not necessary to include a pwmc child node for every channel the hardware supports. define only the channels you need to control. minimal effort, maximum slay 💅✨

the following properties are required for a pwmc device node:

  • compatible — must be the string "freebsd,pwmc". non-negotiable, bestie 🫶
  • reg — the hardware channel number. which channel are we talking about 📌

the following properties are optional for the pwmc device node:

  • label — a string containing only characters legal in a file name. the driver creates an alias with the given name in /dev/pwm which points to the instance's /dev/pwm/pwmcX.Y device entry. your channel, your brand 💖

example of a PWM hardware node containing one pwmc child node — look at her, she's iconic 👑

&ehrpwm0 {
    status = "okay";
    pinctrl-names = "default";
    pinctrl-0 = <&ehrpwm0_AB_pins>;

    pwmcontrol@0 {
        compatible = "freebsd,pwmc";
        reg = <0>;
        label = "backlight";
    };
};

🍓 FILES 🍓

  • /dev/pwm/pwmc* — the character devices themselves. the main characters of this story ⭐

🧚 SEE ALSO 🧚

read them, love them, link them in your group chat 🔗💜

👑 HISTORY 👑

the pwmc driver appeared in FreeBSD 13.0. a legend was born ✨

and that's the whole manual, bestie. go forth and modulate those pulses. you're gonna do amazing 🫶💖

source/version and date, as promised: this page came from the Debian collection, dated June 17, 2019. mwah 💋

📦 where this page comes from