SYSMON_ENVSYS(9)

💖 SYSMON_ENVSYS(9) 💖

okay so bestie, you found the kernel dev manual page for sysmon_envsys — that's the envsys 2 framework, kernel side, from the Kernel Developer's Manual. grab a snack, this one's a whole journey 🍓

---

✨ NAME ✨

sysmon_envsys — the kernel part of the envsys 2 framework, no cap 💅

---

🌸 SYNOPSIS 🌸

#include <dev/sysmon/sysmonvar.h>

struct sysmon_envsys *
sysmon_envsys_create(void);

void
sysmon_envsys_destroy(struct sysmon_envsys *);

int
sysmon_envsys_register(struct sysmon_envsys *);

void
sysmon_envsys_unregister(struct sysmon_envsys *);

int
sysmon_envsys_sensor_attach(struct sysmon_envsys *, envsys_data_t *);

int
sysmon_envsys_sensor_detach(struct sysmon_envsys *, envsys_data_t *);

void
sysmon_envsys_sensor_event(struct sysmon_envsys *, envsys_data_t *,
    int);

void
sysmon_envsys_foreach_sensor(sysmon_envsys_callback_t, void *, bool);

int
sysmon_envsys_update_limits(struct sysmon_envsys *, envsys_data_t *);

---

🦋 DESCRIPTION 🦋

sysmon_envsys is the kernel part of the envsys(4) framework. so basically, with this framework you can:

• register and unregister a sysmon_envsys device 👑
• attach or detach sensors into a device 🎀
• enable or disable automatic monitoring for some sensors without any user interactivity

…among other things, iykyk 💫

💜 HOW TO USE THE FRAMEWORK 💜

so to register a new driver to the sysmon_envsys framework, you first gotta allocate and initialize a sysmon_envsys object — and the function for that is sysmon_envsys_create() ✨ it returns a zero'ed pointer to a sysmon_envsys structure. clean. fresh. iconic.

once the object is initialized, actual sensors may be initialized and attached (peep the “SENSOR DETAILS” section if you want the tea ☕). this is done with the sysmon_envsys_sensor_attach() function, which takes the envsys_data_t (that's a sensor, bestie) in the second argument and attaches it into the sysmon_envsys object from the first argument. slay.

finally, after all the sensors are attached, the device needs to set some required (and optional) members of the sysmon_envsys structure before calling the sysmon_envsys_register() function to register the device. don't skip this step fr fr 🙈

if something goes sideways during initialization and you hit errors, that's what sysmon_envsys_destroy() is for 💀 it detaches all previously attached sensors and deallocates the sysmon_envsys object. clean exit, no mess.

some sensors can be monitored, and when the sensor value changes, an event can be delivered to the powerd(8) daemon 👑 sensor monitoring can be done by the sysmon_envsys framework on a polled basis. OR, alternatively, the sensor's device driver can just call the sysmon_envsys_sensor_event() function to deliver the event without waiting for the device to be polled. main character energy, honestly.

the sysmon_envsys_foreach_sensor() function can be used by other parts of the kernel to iterate over all registered sensors 🔥 this capability is used by the i386/apm(4) driver to summarize the state of all battery sensors. cute.

drivers can also call the sysmon_envsys_update_limits() function when it's necessary to reinitialize a sensor's threshold values 💅 this is used by the acpibat(4) driver when a new battery is inserted. very demure, very mindful.

the sysmon_envsys structure is defined as follows (only the public members are shown):

struct sysmon_envsys {
        const char      *sme_name;
        int             sme_flags;
        int             sme_class;
        uint64_t        sme_events_timeout;
        void            *sme_cookie;
        void (*sme_refresh)(struct sysmon_envsys *, envsys_data_t *);
        void (*sme_set_limits)(struct sysmon_envsys *, envsys_data_t *,
                               sysmon_envsys_lim_t *, uint32_t *);
        void (*sme_get_limits)(struct sysmon_envsys *, envsys_data_t *,
                               sysmon_envsys_lim_t *, uint32_t *);
};

the members have the following meaning, bestie:

• sme_class — this specifies the class of the sysmon envsys device. see the DEVICE CLASSES section for more info (OPTIONAL).
• sme_name — the name that will be used in the driver (REQUIRED) ⭐
• sme_flags — additional flags for the sysmon_envsys device. currently supporting SME_DISABLE_REFRESH. if enabled, the sme_refresh function callback won't be used to refresh sensor data, and the driver will use its own method (OPTIONAL).
• sme_events_timeout — this is used to specify the default timeout value (in seconds) that will be used to check for critical events if any monitoring flag was set (OPTIONAL).

if the driver wants to refresh sensors data via the sysmon_envsys framework, the following members may be specified 👇

• sme_cookie — typically a pointer to the device struct (also called “softc”). this may be used in the sme_refresh, sme_get_limits, or sme_set_limits function callbacks 🍓
• sme_refresh — pointer to a function that will be used to refresh sensor data in the device. this can be used to set the state and other properties of the sensor depending on the data returned by the driver. NOTE: you don't have to refresh all sensors, only the sensor specified by the edata->sensor index 🎯 if this member is not specified, the device driver will be totally responsible for all updates of this sensor; the sysmon_envsys framework will not be able to update the sensor value. no thoughts, head empty, your problem now.
• sme_get_limits — pointer to a function that will be used to obtain from the driver the initial limits (or thresholds) used when monitoring a sensor's value. (see the “SENSOR DETAILS” section for more info.) if this member is not specified, the ENVSYS_FMONLIMITS flag will be ignored, and limit monitoring will not occur until appropriate limits are enabled from userland via envstat(8). so like… nothing happens until you say so 💀
• sme_set_limits — pointer to a function that alerts the device driver whenever monitoring limits (or thresholds) are updated by the user. setting this function allows the device driver to reprogram hardware limits (if provided by the device) when the user-specified limits are updated, and gives the driver direct control over setting the sensor's state based on hardware status 👑

the sme_set_limits callback can be invoked with the third argument (a pointer to the new limits) set to a NULL pointer. device drivers must recognize this as a request to restore the sensor limits to their original, boot-time values 🫶

if the sme_set_limits member is not specified, the device driver is not informed of changes to the sensor's limit values, and the sysmon_envsys framework performs all limit checks in software.

note that it's not necessary to refresh the sensors data before the driver is registered — only do it if you need the data in your driver to check for a specific condition 💫

the timeout value for the monitoring events on a device may be changed via the ENVSYS_SETDICTIONARY ioctl(2) or the envstat(8) command. very handy.

to unregister a driver previously registered with the sysmon_envsys framework, you must use the sysmon_envsys_unregister() function 🌈 if there were monitoring events registered for the driver, they all get destroyed before the device is unregistered and its sensors are detached. finally the sysmon_envsys object will be freed, so there's no need to call sysmon_envsys_destroy(). don't double-dip, bestie 🙈

🧚 DEVICE CLASSES 🧚

the sme_class member of the sysmon_envsys structure is an optional flag that specifies the class of the sysmon envsys device. currently there are two classes:

SME_CLASS_ACADAPTER

this class is for devices that want to act as an AC adapter 🔌 the device writer must ensure that at least there is a sensor with units of ENVSYS_INDICATOR. this will be used to report its current state (on/off). simple, effective, iconic.

SME_CLASS_BATTERY

this class is for devices that want to act as a Battery 🔋 the device writer must ensure that at least there are two sensors with units of ENVSYS_BATTERY_CAPACITY and ENVSYS_BATTERY_CHARGE.

these two sensors are used to ensure that the battery device can send a low-power event to the powerd(8) daemon (if running) when all battery devices are in a critical state 💀 (the critical state occurs when a battery is not currently charging and its charge state is low or critical.) when the low-power condition is met, an event is sent to the powerd(8) daemon (if running), which will shutdown the system gracefully by executing the /etc/powerd/scripts/sensor_battery script 📜✨

if powerd(8) is not running, the system will be powered off via the cpu_reboot(9) call with the RB_POWERDOWN flag. abrupt, but like, necessary.

NOTE: if a SME_CLASS_ACADAPTER or SME_CLASS_BATTERY class device doesn't have the sensors required, the low-power event will never be sent, and the graceful shutdown won't be possible. so pls. attach your sensors. i'm begging 🥺

🎀 SENSOR DETAILS 🎀

each sensor uses a envsys_data_t structure, it's defined as follows (only the public members are shown);

typedef struct envsys_data {
        uint32_t        units;
        uint32_t        state;
        uint32_t        flags;
        uint32_t        rpms;
        int32_t         rfact;
        int32_t         value_cur;
        int32_t         value_max;
        int32_t         value_min;
        int32_t         value_avg;
        sysmon_envsys_lim_t limits;
        int             upropset;
        char            desc[ENVSYS_DESCLEN];
} envsys_data_t;

the members for the envsys_data_t structure have the following meaning:

• units — used to set the units type 🌈
• state — used to set the current state 💫
• flags — used to set additional flags. among other uses, if one or more of the ENVSYS_FMONxxx flags are set, automatic sensor monitoring will be enabled 🔥 periodically, the sensor's value will be checked and if certain conditions are met, an event will be sent to the powerd(8) daemon. NOTE that limits (or thresholds) can be set at any time to enable monitoring that the sensor's value remains within those limits 👑
• rpms — used to set the nominal RPM value for fan sensors 🌀
• rfact — the resistor-factor value for voltage sensors, bestie 💅
• value_cur — the current value
• value_max — the max value
• value_min — the min value
• value_avg — the average value
• limits — the struct that holds the sensor's alarm thresholds 🚨
• upropset — keeps track of which sensor properties are actually set
• desc — the description string. NOTE that it must be unique within a device, and sensors with duplicate or empty descriptions just get straight-up ignored 🙈

Okay so if you're using this framework, there's a whole checklist of stuff you literally cannot skip:

• The desc member has to have a valid description — unique in the device, non-empty, or it's not valid. Periodt.
• The units type must be valid. Here's the whole roster of defined units, no cap:
  • ENVSYS_STEMP — temperature sensors, in microkelvins.
  • ENVSYS_SFANRPM — fan sensors.
  • ENVSYS_SVOLTS_AC — AC Voltage.
  • ENVSYS_SVOLTS_DC — DC Voltage.
  • ENVSYS_SOHMS — Ohms.
  • ENVSYS_SWATTS — Watts.
  • ENVSYS_SAMPS — Ampere.
  • ENVSYS_SWATTHOUR — Watts hour.
  • ENVSYS_SAMPHOUR — Ampere hour.
  • ENVSYS_INDICATOR — for sensors that only want a boolean type.
  • ENVSYS_INTEGER — for sensors that only want an integer type.
  • ENVSYS_DRIVE — for drive sensors.
  • ENVSYS_BATTERY_CAPACITY — for Battery device classes. This sensor unit uses the ENVSYS_BATTERY_CAPACITY_* values in value_cur to report its current capacity to userland. Mandatory if sme_class is set to SME_CLASS_BATTERY.
  • ENVSYS_BATTERY_CHARGE — for Battery device classes. This sensor is equivalent to the Indicator type, it's a boolean. Use it to specify what state the Battery is in: true if the battery is currently charging, false otherwise. Mandatory if sme_class is set to SME_CLASS_BATTERY.
• When you're initializing or refreshing the sensor, the state member should be set to a known state — otherwise it just chills in unknown state, awkward 😭. Possible values:
  • ENVSYS_SVALID — sets the sensor to a valid state.
  • ENVSYS_SINVALID — sets the sensor to an invalid state.
  • ENVSYS_SCRITICAL — sets the sensor to a critical state.
  • ENVSYS_SCRITUNDER — sets the sensor to a critical under state.
  • ENVSYS_SCRITOVER — sets the sensor to a critical over state.
  • ENVSYS_SWARNUNDER — sets the sensor to a warning under state.
  • ENVSYS_SWARNOVER — sets the sensor to a warning over state.
• The flags member accepts one or more of these flags, and yes you can stack them 💅:
  • ENVSYS_FCHANGERFACT — marks the sensor with the ability to change the rfact value on the fly (in voltage sensors). The rfact member must be used in the correct place of the code that retrieves and converts the value of the sensor.
  • ENVSYS_FPERCENT — this uses the value_cur and value_max members to make a percentage. Both values must be enabled and have data.
  • ENVSYS_FVALID_MAX — marks the value_max value as valid.
  • ENVSYS_FVALID_MIN — marks the value_min value as valid.
  • ENVSYS_FVALID_AVG — marks the value_avg value as valid.
  • ENVSYS_FMONCRITICAL — enables and registers a new event to monitor a critical state.
  • ENVSYS_FMONLIMITS — enables and registers a new event to monitor a sensor's value crossing limits or thresholds.
  • ENVSYS_FMONSTCHANGED — enables and registers a new event to monitor battery capacity or drive state sensors. This flag is not effective if the units member is not ENVSYS_DRIVE or ENVSYS_BATTERY_CAPACITY.
  • ENVSYS_FMONNOTSUPP — disallows setting of limits (or thresholds) via the ENVSYS_SETDICTIONARY ioctl(2). This flag only disables setting the limits from userland. It has no effect on monitoring flags set by the driver.
  • ENVSYS_FHAS_ENTROPY — allows this sensor to provide entropy for rnd(4) ✨

And if the driver has to use any of the value_max, value_min, or value_avg members, it should mark them as valid with the appropriate flag. No sneaky unmarked values, bestie 🫶

• If units is set to ENVSYS_DRIVE, the value_cur member must be set to one of these predefined states:
  • ENVSYS_DRIVE_EMPTY — drive state is unknown.
  • ENVSYS_DRIVE_READY — drive is ready.
  • ENVSYS_DRIVE_POWERUP — drive is powering up.
  • ENVSYS_DRIVE_ONLINE — drive is online.
  • ENVSYS_DRIVE_OFFLINE — drive is offline.
  • ENVSYS_DRIVE_IDLE — drive is idle.
  • ENVSYS_DRIVE_ACTIVE — drive is active.
  • ENVSYS_DRIVE_BUILD — drive is building.
  • ENVSYS_DRIVE_REBUILD — drive is rebuilding.
  • ENVSYS_DRIVE_POWERDOWN — drive is powering down.
  • ENVSYS_DRIVE_FAIL — drive has failed.
  • ENVSYS_DRIVE_PFAIL — drive has been degraded.
  • ENVSYS_DRIVE_MIGRATING — drive is migrating.
  • ENVSYS_DRIVE_CHECK — drive is checking its state.
• If units is set to ENVSYS_BATTERY_CAPACITY, the value_cur member must be set to one of these predefined capacity states 🔋:
  • ENVSYS_BATTERY_CAPACITY_NORMAL — battery charge is normal.
  • ENVSYS_BATTERY_CAPACITY_CRITICAL — battery charge is critical.
  • ENVSYS_BATTERY_CAPACITY_LOW — battery charge is low.
  • ENVSYS_BATTERY_CAPACITY_WARNING — battery charge is on or below the warning capacity.
• The envsys(4) framework expects the values to be converted to a unit that can be converted to another one easily. That means you (the user) should convert the value returned by the driver to the appropriate unit. Like voltage sensors to mV, temperature sensors to uK, Watts to mW, Ampere to mA, etc.

These types shouldn't need any conversion at all: ENVSYS_BATTERY_CAPACITY, ENVSYS_BATTERY_CHARGE, ENVSYS_INDICATOR, ENVSYS_INTEGER, and ENVSYS_DRIVE.

PLEASE NOTE THAT YOU MUST AVOID USING FLOATING POINT OPERATIONS IN KERNEL WHEN CONVERTING THE DATA RETURNED BY THE DRIVER TO THE APPROPRIATE UNIT, IT'S NOT ALLOWED. 💀 Like, seriously, do not. Floating point in kernel is not the vibe.

---

🌸 HOW TO ENABLE AUTOMATIC MONITORING IN SENSORS 🌸

Okay this example is literally iconic — it shows how to enable automatic monitoring in a virtual driver for a critical state in the first sensor (sc_sensor[0]):

int
mydriver_initialize_sensors(struct mysoftc *sc)
{
        ...
        /* sensor is initialized with a valid state */
        sc->sc_sensor[0].state = ENVSYS_SVALID;

        /*
         * the monitor member must be true to enable
         * automatic monitoring.
         */
        sc->sc_sensor[0].monitor = true;

        /* and now we specify the type of the monitoring event */
        sc->sc_sensor[0].flags |= ENVSYS_FMONCRITICAL;
        ...
}

int
mydriver_refresh(struct sysmon_envsys *sme, envsys_data_t *edata)
{
        struct mysoftc *sc = sme->sme_cookie;

        /* we get current data from the driver */
        edata->value_cur = sc->sc_getdata();

        /*
         * if value is too high, mark the sensor in
         * critical state.
         */
        if (edata->value_cur > MYDRIVER_SENSOR0_HIWAT) {
                edata->state = ENVSYS_SCRITICAL;
                /* a critical event will be sent now automatically */
        } else {
                /*
                 * if value is within the limits, and we came from
                 * a critical state make sure to change sensor's state
                 * to valid.
                 */
                edata->state = ENVSYS_SVALID;
        }
        ...
}

---

🦋 CODE REFERENCES 🦋

The envsys 2 framework is implemented within these files, bestie:

sys/dev/sysmon/sysmon_envsys.c

sys/dev/sysmon/sysmon_envsys_events.c

sys/dev/sysmon/sysmon_envsys_tables.c

sys/dev/sysmon/sysmon_envsys_util.c

⭐ SEE ALSO ⭐

envsys(4), envstat(8) — go read those next, iykyk 🫶

🎀 HISTORY 🎀

The first envsys framework first appeared in NetBSD 1.5. The envsys 2 framework first appeared in NetBSD 5.0. Glow-up of the century, honestly.

👑 AUTHORS 👑

The (current) envsys 2 framework was implemented by Juan Romero Pardines. Additional input on the design was provided by many NetBSD developers around the world 🌈

The first envsys framework was implemented by Jason R. Thorpe, Tim Rightnour, and Bill Squier.

---

And that's the whole page, bestie! 💖 This one's from the Debian distro source, dated July 13, 2012, and it goes by SYSMON_ENVSYS(9) — go forth and monitor those sensors, slay ✨🍓