723 lines
19 KiB
Groff
723 lines
19 KiB
Groff
.\" $NetBSD: sysmon_envsys.9,v 1.46 2017/07/03 21:28:48 wiz Exp $
|
|
.\"
|
|
.\" Copyright (c) 2007, 2008 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 July 13, 2012
|
|
.Dt SYSMON_ENVSYS 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm sysmon_envsys
|
|
.Nd kernel part of the envsys 2 framework
|
|
.Sh SYNOPSIS
|
|
.In dev/sysmon/sysmonvar.h
|
|
.Ft struct sysmon_envsys *
|
|
.Fn sysmon_envsys_create "void"
|
|
.Ft void
|
|
.Fn sysmon_envsys_destroy "struct sysmon_envsys *"
|
|
.Ft int
|
|
.Fn sysmon_envsys_register "struct sysmon_envsys *"
|
|
.Ft void
|
|
.Fn sysmon_envsys_unregister "struct sysmon_envsys *"
|
|
.Ft int
|
|
.Fn sysmon_envsys_sensor_attach "struct sysmon_envsys *" "envsys_data_t *"
|
|
.Ft int
|
|
.Fn sysmon_envsys_sensor_detach "struct sysmon_envsys *" "envsys_data_t *"
|
|
.Ft void
|
|
.Fn sysmon_envsys_sensor_event "struct sysmon_envsys *" "envsys_data_t *" "int"
|
|
.Ft void
|
|
.Fn sysmon_envsys_foreach_sensor "sysmon_envsys_callback_t" "void *" "bool"
|
|
.Ft int
|
|
.Fn sysmon_envsys_update_limits "struct sysmon_envsys *" "envsys_data_t *"
|
|
.Sh DESCRIPTION
|
|
.Pp
|
|
.Nm
|
|
is the kernel part of the
|
|
.Xr envsys 4
|
|
framework.
|
|
With this framework you are able to register and unregister a
|
|
.Nm
|
|
device, attach or detach sensors into a device, and enable or disable
|
|
automatic monitoring for some sensors without any user interactivity,
|
|
among other things.
|
|
.Ss HOW TO USE THE FRAMEWORK
|
|
To register a new driver to the
|
|
.Nm
|
|
framework, a
|
|
.Em sysmon_envsys
|
|
object must be allocated and initialized; the
|
|
.Fn sysmon_envsys_create
|
|
function is used for this.
|
|
This returns a zero'ed pointer to a
|
|
.Em sysmon_envsys
|
|
structure.
|
|
.Pp
|
|
Once the object has been initialized,
|
|
actual sensors may be initialized and attached (see the
|
|
.Sx SENSOR DETAILS
|
|
section for more information).
|
|
This is accomplished by the
|
|
.Fn sysmon_envsys_sensor_attach
|
|
function, which will attach the
|
|
.Em envsys_data_t
|
|
(a sensor) specified as second argument into the
|
|
.Em sysmon_envsys
|
|
object specified in the first argument.
|
|
.Pp
|
|
Finally, after all sensors have been attached,
|
|
the device needs to set some required (and optional) members of the
|
|
.Em sysmon_envsys
|
|
structure before calling the
|
|
.Fn sysmon_envsys_register
|
|
function to register the device.
|
|
.Pp
|
|
In case of errors during the initialization, the
|
|
.Fn sysmon_envsys_destroy
|
|
function should be used.
|
|
This detaches all previously attached sensors and deallocates the
|
|
.Em sysmon_envsys
|
|
object.
|
|
.Pp
|
|
Some sensors can be monitored, and when the sensor value changes an event
|
|
can be delivered to the
|
|
.Xr powerd 8
|
|
daemon.
|
|
Sensor monitoring can be performed by the
|
|
.Nm
|
|
framework on a polled basis.
|
|
Alternatively, the sensor's device driver can call the
|
|
.Fn sysmon_envsys_sensor_event
|
|
function to deliver the event without waiting for the device to be polled.
|
|
.Pp
|
|
The
|
|
.Fn 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
|
|
.Xr i386/apm 4
|
|
driver to summarize the state of all battery sensors.
|
|
.Pp
|
|
Drivers can also call the
|
|
.Fn sysmon_envsys_update_limits
|
|
function when it is necessary to reinitialize a sensor's threshold values.
|
|
This is used by the
|
|
.Xr acpibat 4
|
|
driver when a new battery is inserted.
|
|
.Pp
|
|
The
|
|
.Em sysmon_envsys
|
|
structure is defined as follows
|
|
(only the public members are shown):
|
|
.Bd -literal
|
|
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 *);
|
|
};
|
|
.Ed
|
|
.Pp
|
|
The members have the following meaning:
|
|
.Pp
|
|
.Bl -tag -width "sme_events_timeout"
|
|
.It Fa sme_class
|
|
This specifies the class of the sysmon envsys device.
|
|
See the
|
|
.Sy DEVICE CLASSES
|
|
section for more information (OPTIONAL).
|
|
.It Fa sme_name
|
|
The name that will be used in the driver (REQUIRED).
|
|
.It Fa sme_flags
|
|
Additional flags for the
|
|
.Nm
|
|
device.
|
|
Currently supporting
|
|
.Ar SME_DISABLE_REFRESH .
|
|
If enabled, the
|
|
.Ar sme_refresh
|
|
function callback won't be used
|
|
to refresh sensor data and the driver will use its own method (OPTIONAL).
|
|
.It Fa 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).
|
|
.El
|
|
.Pp
|
|
If the driver wants to refresh sensors data via the
|
|
.Nm
|
|
framework, the following members may be specified:
|
|
.Pp
|
|
.Bl -tag -width "sme_events_timeout"
|
|
.It Fa sme_cookie
|
|
Typically a pointer to the device struct (also called
|
|
.Dq softc ) .
|
|
This may be used in the
|
|
.Sy sme_refresh ,
|
|
.Sy sme_get_limits ,
|
|
or
|
|
.Sy sme_set_limits
|
|
function callbacks.
|
|
.It Fa 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.
|
|
.Em NOTE :
|
|
.Em You don't have to refresh all sensors, only the sensor specified by the
|
|
.Sy edata->sensor
|
|
.Em index .
|
|
If this member is not specified, the device driver will be totally
|
|
responsible for all updates of this sensor; the
|
|
.Nm
|
|
framework will not be able to update the sensor value.
|
|
.It Fa 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
|
|
.Sx SENSOR DETAILS
|
|
section for more information.)
|
|
If this member is not specified, the
|
|
.Dv ENVSYS_FMONLIMITS
|
|
flag will be ignored, and limit monitoring will not occur until
|
|
appropriate limits are enabled from userland via
|
|
.Xr envstat 8 .
|
|
.It Fa 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-specificied limits are
|
|
updated, and gives the driver direct control over setting the sensor's
|
|
state based on hardware status.
|
|
.Pp
|
|
The
|
|
.Fa sme_set_limits
|
|
callback can be invoked with the third argument (a pointer to the new
|
|
limits) set to a
|
|
.Dv NULL
|
|
pointer.
|
|
Device drivers must recognize this as a request to restore the sensor
|
|
limits to their original, boot-time values.
|
|
.Pp
|
|
If the
|
|
.Fa sme_set_limits
|
|
member is not specified, the device driver is not informed of changes to
|
|
the sensor's limit values, and the
|
|
.Nm
|
|
framework performs all limit checks in software.
|
|
.El
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
The timeout value for the monitoring events on a device may be changed via the
|
|
.Dv ENVSYS_SETDICTIONARY
|
|
.Xr ioctl 2
|
|
or the
|
|
.Xr envstat 8
|
|
command.
|
|
.Pp
|
|
To unregister a driver previously registered with the
|
|
.Nm
|
|
framework, the
|
|
.Fn sysmon_envsys_unregister
|
|
function must be used.
|
|
If there were monitoring events registered for the
|
|
driver, they all will be destroyed before the device is unregistered and
|
|
its sensors are detached.
|
|
Finally the
|
|
.Em sysmon_envsys
|
|
object will be freed, so there's no need to call
|
|
.Fn sysmon_envsys_destroy .
|
|
.Ss DEVICE CLASSES
|
|
The
|
|
.Fa sme_class
|
|
member of the
|
|
.Fa sysmon_envsys
|
|
structure is an optional flag that specifies the class of the
|
|
sysmon envsys device.
|
|
Currently there are two classes:
|
|
.Pp
|
|
.Bl -tag -width ident
|
|
.It SME_CLASS_ACADAPTER
|
|
.Pp
|
|
This class is for devices that want to act as an
|
|
.Em AC adapter .
|
|
The device writer must ensure that at least there is a
|
|
sensor with
|
|
.Em units
|
|
of
|
|
.Dv ENVSYS_INDICATOR .
|
|
This will be used to report its current state (on/off).
|
|
.It SME_CLASS_BATTERY
|
|
.Pp
|
|
This class is for devices that want to act as a
|
|
.Em Battery .
|
|
The device writer must ensure that at least there are two sensors with
|
|
units of
|
|
.Dv ENVSYS_BATTERY_CAPACITY
|
|
and
|
|
.Dv ENVSYS_BATTERY_CHARGE .
|
|
.Pp
|
|
These two sensors are used to ensure that the battery device can
|
|
send a
|
|
.Em low-power
|
|
event to the
|
|
.Xr 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
|
|
.Em low-power
|
|
condition is met, an event is sent to the
|
|
.Xr powerd 8
|
|
daemon (if running), which will shutdown the system gracefully
|
|
by executing the
|
|
.Pa /etc/powerd/scripts/sensor_battery
|
|
script.
|
|
.Pp
|
|
If
|
|
.Xr powerd 8
|
|
is not running, the system will be powered off via the
|
|
.Xr cpu_reboot 9
|
|
call with the
|
|
.Dv RB_POWERDOWN
|
|
flag.
|
|
.Pp
|
|
.El
|
|
.Em NOTE :
|
|
If a
|
|
.Dv SME_CLASS_ACADAPTER
|
|
or
|
|
.Dv SME_CLASS_BATTERY
|
|
class device doesn't have the sensors required, the
|
|
.Em low-power
|
|
event will never be sent, and the graceful shutdown won't be possible.
|
|
.Ss SENSOR DETAILS
|
|
Each sensor uses a
|
|
.Sy envsys_data_t
|
|
structure, it's defined as follows (only the public members are shown);
|
|
.Bd -literal
|
|
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;
|
|
.Ed
|
|
.Pp
|
|
The members for the
|
|
.Sy envsys_data_t
|
|
structure have the following meaning:
|
|
.Pp
|
|
.Bl -tag -width cdoscdosrunru
|
|
.It Fa units
|
|
Used to set the units type.
|
|
.It Fa state
|
|
Used to set the current state.
|
|
.It Fa flags
|
|
Used to set additional flags.
|
|
Among other uses, if one or more of the
|
|
.Dv 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
|
|
.Xr powerd 8
|
|
daemon.
|
|
.Em NOTE
|
|
.Em that limits (or thresholds) can be set at any time to enable
|
|
.Em monitoring that the sensor's value remains within those limits .
|
|
.It Fa rpms
|
|
Used to set the nominal RPM value for
|
|
.Sy fan
|
|
sensors.
|
|
.It Fa rfact
|
|
Used to set the rfact value for
|
|
.Sy voltage
|
|
sensors.
|
|
.It Fa value_cur
|
|
Used to set the current value.
|
|
.It Fa value_max
|
|
Used to set the maximum value.
|
|
.It Fa value_min
|
|
Used to set the minimum value.
|
|
.It Fa value_avg
|
|
Used to set the average value.
|
|
.It Fa limits
|
|
Structure used to contain the sensor's alarm thresholds.
|
|
.It Fa upropset
|
|
Used to keep track of which sensor properties are set.
|
|
.It Fa desc
|
|
Used to set the description string.
|
|
.Em NOTE
|
|
.Em that the description string must be unique in a device, and sensors with
|
|
.Em duplicate or empty description will simply be ignored .
|
|
.El
|
|
.Pp
|
|
Users of this framework must take care about the following points:
|
|
.Bl -bullet
|
|
.It
|
|
The
|
|
.Ar desc
|
|
member needs to have a valid description, unique in a device and non empty
|
|
to be valid.
|
|
.It
|
|
The
|
|
.Ar units
|
|
type must be valid.
|
|
The following units are defined:
|
|
.Pp
|
|
.Bl -tag -width "ENVSYS_BATTERY_CAPACITY" -compact
|
|
.It Dv ENVSYS_STEMP
|
|
For temperature sensors, in microkelvins.
|
|
.It Dv ENVSYS_SFANRPM
|
|
For fan sensors.
|
|
.It Dv ENVSYS_SVOLTS_AC
|
|
For AC Voltage.
|
|
.It Dv ENVSYS_SVOLTS_DC
|
|
For DC Voltage.
|
|
.It Dv ENVSYS_SOHMS
|
|
For Ohms.
|
|
.It Dv ENVSYS_SWATTS
|
|
For Watts.
|
|
.It Dv ENVSYS_SAMPS
|
|
For Ampere.
|
|
.It Dv ENVSYS_SWATTHOUR
|
|
For Watts hour.
|
|
.It Dv ENVSYS_SAMPHOUR
|
|
For Ampere hour.
|
|
.It Dv ENVSYS_INDICATOR
|
|
For sensors that only want a boolean type.
|
|
.It Dv ENVSYS_INTEGER
|
|
For sensors that only want an integer type.
|
|
.It Dv ENVSYS_DRIVE
|
|
For drive sensors.
|
|
.It Dv ENVSYS_BATTERY_CAPACITY
|
|
For Battery device classes.
|
|
This sensor unit uses the
|
|
.Dv ENVSYS_BATTERY_CAPACITY_*
|
|
values in
|
|
.Ar value_cur
|
|
to report its current capacity to userland.
|
|
Mandatory if
|
|
.Fa sme_class
|
|
is set to
|
|
.Dv SME_CLASS_BATTERY .
|
|
.It Dv ENVSYS_BATTERY_CHARGE
|
|
For Battery device classes.
|
|
This sensor is equivalent to the Indicator type, it's a boolean.
|
|
Use it to specify in what state is the Battery state:
|
|
.Sy true
|
|
if the battery is currently charging or
|
|
.Sy false
|
|
otherwise.
|
|
Mandatory if
|
|
.Fa sme_class
|
|
is set to
|
|
.Dv SME_CLASS_BATTERY .
|
|
.El
|
|
.It
|
|
When initializing or refreshing the sensor, the
|
|
.Ar state
|
|
member should be set to a known state (otherwise it will be in
|
|
unknown state).
|
|
Possible values:
|
|
.Pp
|
|
.Bl -tag -width "ENVSYS_SCRITUNDERXX" -compact
|
|
.It Dv ENVSYS_SVALID
|
|
Sets the sensor to a valid state.
|
|
.It Dv ENVSYS_SINVALID
|
|
Sets the sensor to an invalid state.
|
|
.It Dv ENVSYS_SCRITICAL
|
|
Sets the sensor to a critical state.
|
|
.It Dv ENVSYS_SCRITUNDER
|
|
Sets the sensor to a critical under state.
|
|
.It Dv ENVSYS_SCRITOVER
|
|
Sets the sensor to a critical over state.
|
|
.It Dv ENVSYS_SWARNUNDER
|
|
Sets the sensor to a warning under state.
|
|
.It Dv ENVSYS_SWARNOVER
|
|
Sets the sensor to a warning over state.
|
|
.El
|
|
.Pp
|
|
.It
|
|
The
|
|
.Ar flags
|
|
member accepts one or more of the following flags:
|
|
.Pp
|
|
.Bl -tag -width "ENVSYS_FCHANGERFACTXX"
|
|
.It Dv ENVSYS_FCHANGERFACT
|
|
Marks the sensor with ability to change the
|
|
.Ar rfact
|
|
value on the fly (in voltage sensors).
|
|
The
|
|
.Ar rfact
|
|
member must be used in the correct place of the code
|
|
that retrieves and converts the value of the sensor.
|
|
.It Dv ENVSYS_FPERCENT
|
|
This uses the
|
|
.Ar value_cur
|
|
and
|
|
.Ar value_max
|
|
members to make a percentage.
|
|
Both values must be enabled and have data.
|
|
.It Dv ENVSYS_FVALID_MAX
|
|
Marks the
|
|
.Ar value_max
|
|
value as valid.
|
|
.It Dv ENVSYS_FVALID_MIN
|
|
Marks the
|
|
.Ar value_min
|
|
value as valid.
|
|
.It Dv ENVSYS_FVALID_AVG
|
|
Marks the
|
|
.Ar value_avg
|
|
value as valid.
|
|
.It Dv ENVSYS_FMONCRITICAL
|
|
Enables and registers a new event to monitor a critical state.
|
|
.It Dv ENVSYS_FMONLIMITS
|
|
Enables and registers a new event to monitor a sensor's value crossing
|
|
limits or thresholds.
|
|
.It Dv ENVSYS_FMONSTCHANGED
|
|
Enables and registers a new event to monitor battery capacity or drive state
|
|
sensors.
|
|
The flag is not effective if the
|
|
.Ar units
|
|
member is not
|
|
.Dv ENVSYS_DRIVE
|
|
or
|
|
.Dv ENVSYS_BATTERY_CAPACITY .
|
|
.It Dv ENVSYS_FMONNOTSUPP
|
|
Disallows setting of limits (or thresholds) via the
|
|
.Dv ENVSYS_SETDICTIONARY
|
|
.Xr ioctl 2 .
|
|
This flag only disables setting the limits from userland.
|
|
It has no effect on monitoring flags set by the driver.
|
|
.It Dv ENVSYS_FHAS_ENTROPY
|
|
Allows this sensor to provide entropy for
|
|
.Xr rnd 4 .
|
|
.El
|
|
.Pp
|
|
.Em If the driver has to use any of the
|
|
.Ar value_max ,
|
|
.Ar value_min ,
|
|
.Em or
|
|
.Ar value_avg
|
|
.Em members, they should be marked as valid with the appropriate flag .
|
|
.Pp
|
|
.It
|
|
If
|
|
.Ar units
|
|
is set to
|
|
.Dv ENVSYS_DRIVE ,
|
|
the
|
|
.Ar value_cur
|
|
member must be set to one of the following predefined states:
|
|
.Pp
|
|
.Bl -tag -width "ENVSYS_DRIVE_POWERDOWNXX" -compact
|
|
.It Dv ENVSYS_DRIVE_EMPTY
|
|
Drive state is unknown.
|
|
.It Dv ENVSYS_DRIVE_READY
|
|
Drive is ready.
|
|
.It Dv ENVSYS_DRIVE_POWERUP
|
|
Drive is powering up.
|
|
.It Dv ENVSYS_DRIVE_ONLINE
|
|
Drive is online.
|
|
.It Dv ENVSYS_DRIVE_OFFLINE
|
|
Drive is offline.
|
|
.It Dv ENVSYS_DRIVE_IDLE
|
|
Drive is idle.
|
|
.It Dv ENVSYS_DRIVE_ACTIVE
|
|
Drive is active.
|
|
.It Dv ENVSYS_DRIVE_BUILD
|
|
Drive is building.
|
|
.It Dv ENVSYS_DRIVE_REBUILD
|
|
Drive is rebuilding.
|
|
.It Dv ENVSYS_DRIVE_POWERDOWN
|
|
Drive is powering down.
|
|
.It Dv ENVSYS_DRIVE_FAIL
|
|
Drive has failed.
|
|
.It Dv ENVSYS_DRIVE_PFAIL
|
|
Drive has been degraded.
|
|
.It Dv ENVSYS_DRIVE_MIGRATING
|
|
Drive is migrating.
|
|
.It Dv ENVSYS_DRIVE_CHECK
|
|
Drive is checking its state.
|
|
.El
|
|
.Pp
|
|
.It
|
|
If
|
|
.Ar units
|
|
is set to
|
|
.Dv ENVSYS_BATTERY_CAPACITY ,
|
|
the
|
|
.Ar value_cur
|
|
member must be set to one of the following predefined capacity states:
|
|
.Pp
|
|
.Bl -tag -width "ENVSYS_BATTERY_CAPACITY_CRITICAL" -compact
|
|
.It Dv ENVSYS_BATTERY_CAPACITY_NORMAL
|
|
Battery charge is normal.
|
|
.It Dv ENVSYS_BATTERY_CAPACITY_CRITICAL
|
|
Battery charge is critical.
|
|
.It Dv ENVSYS_BATTERY_CAPACITY_LOW
|
|
Battery charge is low.
|
|
.It Dv ENVSYS_BATTERY_CAPACITY_WARNING
|
|
Battery charge is on or below the warning capacity.
|
|
.El
|
|
.It
|
|
The
|
|
.Xr envsys 4
|
|
framework expects to have the values converted to
|
|
a unit that can be converted to another one easily.
|
|
That means the user
|
|
should convert the value returned by the driver to the appropriate unit.
|
|
For example voltage sensors to
|
|
.Sy mV ,
|
|
temperature sensors to
|
|
.Sy uK ,
|
|
Watts to
|
|
.Sy mW ,
|
|
Ampere to
|
|
.Sy mA ,
|
|
etc.
|
|
.Pp
|
|
The following types shouldn't need any conversion:
|
|
.Dv ENVSYS_BATTERY_CAPACITY ,
|
|
.Dv ENVSYS_BATTERY_CHARGE ,
|
|
.Dv ENVSYS_INDICATOR ,
|
|
.Dv ENVSYS_INTEGER ,
|
|
and
|
|
.Dv ENVSYS_DRIVE .
|
|
.Pp
|
|
.Em PLEASE NOTE THAT YOU MUST AVOID USING FLOATING POINT OPERATIONS
|
|
.Em IN KERNEL WHEN CONVERTING THE DATA RETURNED BY THE DRIVER TO THE
|
|
.Em APPROPRIATE UNIT, IT'S NOT ALLOWED .
|
|
.Pp
|
|
.El
|
|
.Ss HOW TO ENABLE AUTOMATIC MONITORING IN SENSORS
|
|
The following example illustrates how to enable automatic monitoring
|
|
in a virtual driver for a
|
|
.Em critical
|
|
state in the first sensor
|
|
.Fa ( sc_sensor[0] ) :
|
|
.Pp
|
|
.Bd -literal
|
|
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;
|
|
}
|
|
...
|
|
}
|
|
.Ed
|
|
.Sh CODE REFERENCES
|
|
The
|
|
.Sy envsys 2
|
|
framework is implemented within the files:
|
|
.Pp
|
|
.Pa sys/dev/sysmon/sysmon_envsys.c
|
|
.Pp
|
|
.Pa sys/dev/sysmon/sysmon_envsys_events.c
|
|
.Pp
|
|
.Pa sys/dev/sysmon/sysmon_envsys_tables.c
|
|
.Pp
|
|
.Pa sys/dev/sysmon/sysmon_envsys_util.c
|
|
.Sh SEE ALSO
|
|
.Xr envsys 4 ,
|
|
.Xr envstat 8
|
|
.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.
|
|
.Pp
|
|
The first
|
|
.Em envsys
|
|
framework was implemented by
|
|
Jason R. Thorpe, Tim Rightnour, and Bill Squier.
|