Copyright (c) 2007 The NetBSD Foundation, Inc.
All rights reserved.
This code is derived from software contributed to The NetBSD Foundation
by Juan Romero Pardines.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
.Dd May 4, 2021 .Dt ENVSYS 4 .Os .Sh NAME .Nm envsys .Nd Environmental Systems framework (version 2) .Sh SYNOPSIS n sys/envsys.h .Sh DESCRIPTION The .Nm framework provides support to handle hardware monitor devices. Hardware monitoring chips are able to report values from different types of sensors.
p The .Nm framework consists of two parts:
p l -enum -offset indent -compact t the userland part, to receive the current sensor data and to set some properties on sensors: .Xr envstat 8 . t The kernel part that is able to talk to the devices providing sensor data: .Xr sysmon_envsys 9 . .El
p The .Nm framework uses .Xr proplib 3 for communication between kernel and user space. The following .Xr ioctl 2 types are available: l -tag -width XX t Dv ENVSYS_GETDICTIONARY Pq prop_dictionary_t
p This .Xr ioctl 2 is used to receive the global dictionary that is being used in the kernel by the .Xr sysmon_envsys 9 framework. It will contain an array of dictionaries per device and one dictionary per sensor plus another special dictionary that contains the properties for a device. Each sensor dictionary will have its own characteristics and values.
p
The following XML property list represents a virtual device
.Dq device0
with one entry for sensor
.Dq sensor0
and all available properties set on it, plus another entry for the
.Dq device-properties
dictionary (which contains specific properties for a device):
d -literal
p Let's explain some more about those objects: l -tag -width "monitoring-state-critical-overxx" t Fa allow-rfact Set to .Em true means that the sensor is able to change the resistor factor, only used in Voltage sensors. t Fa avg-value Current average value in the sensor. t Fa battery-capacity Current capacity state for a battery capacity sensor. t Fa critical-capacity Critical capacity set previously by the .Dv ENVSYS_SETDICTIONARY .Xr ioctl 2 . Only available on sensors with the .Em want-percentage object enabled. t Fa critical-max Critical max limit set previously by the .Dv ENVSYS_SETDICTIONARY .Xr ioctl 2 . t Fa critical-min Critical min limit set previously by the .Dv ENVSYS_SETDICTIONARY .Xr ioctl 2 . t Fa cur-value Current value in the sensor. t Fa description Description of the sensor. t Fa high-capacity High capacity set previously by the .Dv ENVSYS_SETDICTIONARY .Xr ioctl 2 . Only available on sensors with the .Em want-percentage object enabled. Used to monitor possible over-charging of batteries. t Fa index Index position of the sensor. t Fa max-value Current max value in the sensor. t Fa maximum-capacity Maximum capacity set previously by the .Dv ENVSYS_SETDICTIONARY .Xr ioctl 2 . Only available on sensors with the .Em want-percentage object enabled. Used to monitor possible over-charging of batteries. t Fa min-value Current min value in the sensor. t Fa monitoring-state-critical If true, the device has enabled the flag to monitor a critical state. t Fa monitoring-state-hw-range-limits If true, the device has enabled the flag to monitor warning or critical limits. t Fa monitoring-state-state-changed If true, the device has enabled the flag to monitor for state changes in a drive or Battery state sensor. t Fa monitoring-supported If true, critical/warning capacity/max/min limits may be set by the .Dv ENVSYS_SETDICTIONARY .Xr ioctl 2 . t Fa state Current state in the sensor. t Fa type Type of unit in the sensor. t Fa want-percentage If true, .Em max-value and .Em cur-value are valid and a percentage may be computed from them. t Fa warning-capacity Warning capacity set previously by the .Dv ENVSYS_SETDICTIONARY .Xr ioctl 2 . Only available on sensors with the .Em want-percentage object enabled. t Fa warning-max Warning max limit set previously by the .Dv ENVSYS_SETDICTIONARY .Xr ioctl 2 . t Fa warning-min Warning min limit set previously by the .Dv ENVSYS_SETDICTIONARY .Xr ioctl 2 . .El t Dv ENVSYS_REMOVEPROPS Pq prop_dictionary_t
p This .Xr ioctl 2 is used to remove all properties that are currently set via the .Dv ENVSYS_SETDICTIONARY ioctl. The values will be set to defaults, the ones that the device uses.
p Only one object is allowed on this dictionary: d -literal -offset ident <key>envsys-remove-props</key> <true/> .Ed
p
It is a boolean object and must be set to
.Em true
to be effective.
t Dv ENVSYS_SETDICTIONARY Pq prop_dictionary_t This
.Xr ioctl 2
is used to send a dictionary with new properties that should be
processed by the
.Nm
framework.
Only a set of predefined keywords are recognized by the kernel part.
The following is the property list representation
of a dictionary with all recognized and required keywords that
a sensor understands:
d -literal
p
Also if some properties in a device need to be changed, the
.Dq device-properties
dictionary must be used.
At this moment only the
.Dq refresh-timeout
property is understood.
This has the following structure:
d -literal
p
A dictionary sent to the kernel with this
.Xr ioctl 2
should have the following structure:
d -literal
p The named device will be an array and will contain dictionaries, any dictionary needs to have the .Em index object specifying the sensor that is required for the new properties.
p If an unknown object was sent with the dictionary, .Er EINVAL will be returned, or if the sensor does not support changing rfact (voltage sensors) or critical/warning/capacity limits, .Er ENOTSUP will be returned. .El
p Additionally, the following .Xr ioctl 2 commands are provided for compatibility purposes for applications written against the original experimental .Nm API available between .Nx 1.5 and .Nx 4.0 ; they have been deprecated since .Nx 5.0 , and may be removed at any time: l -tag -width Ds t Dv ENVSYS_GTREDATA Pq envsys_tre_data_t t Dv ENVSYS_GTREINFO Pq envsys_basic_info_t .El .Sh NOTES When setting a critical/warning max or min limit with the .Dv ENVSYS_SETDICTIONARY .Xr ioctl 2 , the user must be aware that .Xr sysmon_envsys 9 expects to have a proper unit, so the value must be converted. Please see .Xr sysmon_envsys 9 for more information.
p Also when setting a critical or warning capacity limit, the formula to send a proper value to .Xr sysmon_envsys 9 is the following: .Em value = (value / 100) * max value . The max value is available in the sensor's dictionary. .Sh EXAMPLES The following example shows how to change the description of .Ql sensor0 in the .Ql aibs0 device with the .Dv ENVSYS_SETDICTIONARY .Xr ioctl 2 : d -literal int main(void) { prop_dictionary_t global_dict, sensor_dict; prop_array_t array; prop_object_t obj; int fd, error; global_dict = prop_dictionary_create(); sensor_dict = prop_dictionary_create(); array = prop_array_create(); if (!prop_dictionary_set(global_dict, "aibs0", array)) err(EINVAL, "prop_dictionary_set global"); obj = prop_string_create_nocopy("sensor0"); if (obj == NULL || !prop_dictionary_set(sensor_dict, "index", obj)) err(EINVAL, "sensor index"); prop_object_release(obj); /* new description */ obj = prop_string_create_cstring_nocopy("CPU core voltage"); if (obj == NULL || !prop_dictionary_set(sensor_dict, "description", obj)) err(EINVAL, "new description"); prop_object_release(obj); if (!prop_array_add(array, sensor_dict)) err(EINVAL, "prop_array_add"); if ((fd = open(_PATH_SYSMON, O_RDWR)) == -1) err(EXIT_FAILURE, "open"); /* we are done, send the dictionary */ error = prop_dictionary_send_ioctl(global_dict, fd, ENVSYS_SETDICTIONARY); prop_object_release(array); prop_object_release(sensor_dict); prop_object_release(global_dict); (void)close(fd); return error; } .Ed .Sh SEE ALSO .Xr envsys.conf 5 , .Xr envstat 8 , .Xr powerd 8 , .Xr sysmon_envsys 9 .Sh HISTORY The first .Em envsys framework first appeared in .Nx 1.5 . The .Em envsys 2 framework first appeared in .Nx 5.0 . .Sh AUTHORS The (current) .Em envsys 2 framework was implemented by .An Juan Romero Pardines . Additional input on the design was provided by many .Nx developers around the world.
p The first .Em envsys framework was implemented by Jason R. Thorpe, Tim Rightnour, and Bill Squier.
Indexes created Wed Sep 24 05:09:52 GMT 2025