KSENSOR(9E) Driver Entry Points KSENSOR(9E)

NAME

ksensor - kernel sensor framework

SYNOPSIS

#include <sys/sensors.h>

INTERFACE LEVEL

Volatile - This interface is still evolving in illumos. API and ABI
stability is not guaranteed.

DESCRIPTION

The ksensor, kernel sensor, framework provides a means for drivers to
provide various kinds of sensor information to userland such as
temperature, voltage, current, and control sensors. Sensors are
exposed in /dev/sensors and the framework takes care of managing minor
nodes and ioctl interfaces. The driver does not need to expose a
character device interface nor are its minor nodes used.

Sensor Types, Kinds, Units and Naming
Sensors are broken into different types. The types describe the shape
of the value that can be read from the sensor itself. Currently,
scalar sensors are the only supported sensor type. A scalar sensor has
several properties:

unit: uint32_t
The unit of the sensor, discussed below, indicates how to
interpret the value itself.

granularity: int32_t
The granularity indicates the number of increments per unit in
the measurement. A value such as 10 indicates that the value
is in 10ths of the unit. If this was a temperature sensor, one
would need to divide by 10 to get the value into degrees. On
the other hand a negative granularity indicates one would need
to multiply the value to get the actual units. For example, a
value of -2 would indicate that you'd need to multiply the
value by two to get the actual number of degrees.

precision: uint32_t
The precision represents the accuracy of the sensor itself and
is measured in units of the granularity. For example, a
temperature sensor that has a granularity of 1, meaning the
value read from the sensor is in degrees, and is accurate to
+/-5 degrees would set the precision to 5. Conversely, a
temperature sensor that measured in 0.5 degree increments has a
granularity of 2. If the sensor was accurate to +/-1 degree,
then it'd have a precision of 2. If the precision is unknown,
it should be left at zero.

value: int64_t
The value is the actual reading from the sensor and it is
interpreted according to the granularity. This is a signed
value as the value may be negative or positive depending on the
unit.

In addition to the type, sensors also have a notion of a kind, which
indicates what kind of physical property the sensor measures. The
kernel defines the kinds currently:

SENSOR_KIND_TEMPERATURE
This measures temperature, potentially in degrees
Celsius, Fahrenheit, or Kelvin. This is one of the more
common kinds of sensors in the system, as many ASICs
embed temperature sensors for health and monitoring.

SENSOR_KIND_VOLTAGE
Voltage sensors measure the amount of voltage at a
particular point in a circuit. This is one part of
determining how much power a device is consuming. While
some ASICs and ICs operate at a fixed voltage range, many
support operating at diverse ranges and can dynamically
vary their voltage.

SENSOR_KIND_CURRENT
Current sensors measure the total numbers of amps that
are passing through a measurement point on a circuit
(which may be indirect). This is often a proxy for
measuring how much power something is using as many
computer related electronics operate at a fixed voltage.

SENSOR_KIND_SYNTHETIC
A synthetic sensor is different from the others in that
it does not actually measure an actual physical
phenomenon. Synthetic sensors are generally a unitless
measure on some fixed scale. That measure is often
derived from some actual physical measurement, which is
why synthetic sensors have the ability to indicate that
their measurement is derived from another kind of sensor.
To make this more concrete, let's look at an example.

The smntemp(4D) driver exposes the AMD Tctl sensor, which
is a control temperature value. This is not a
measurement in degrees C, but rather is a value from 0 to
100 where 100 indicates that a thermal shutdown is
imminent. This value is synthesized and transformed from
several different temperature samples and goes through
its own algorithm, but critically the resulting synthetic
Tctl sensor does not represent a temperature, but is used
to power cooling control loops.

SENSOR_KIND_UNKNOWN
This value is used by the framework to indicate a kind
was not reported. Drivers should not use this value.

From here, a given measurement that occurs also has a unit that is
associated with it. The following sensors are supported:

SENSOR_UNIT_CELSIUS
Indicates that the sensor measure degrees in Celsius (C).

SENSOR_UNIT_FAHRENHEIT
Indicates that the sensor measure degrees in Fahrenheit
(F).

SENSOR_UNIT_KELVIN
Indicates that the sensor measure degrees in Kelvin (K).

SENSOR_UNIT_VOLTS
Indicates that the sensor measures voltage in Volts (V).

SENSOR_UNIT_AMPS
Indicates that the sensor measures current in Amperes
(A).

SENSOR_UNIT_NONE
This unit indicates that there is no unit because there
is associated physical property. This should be used by
SENSOR_KIND_SYNTHETIC sensors.

SENSOR_UNIT_UNKNOWN
This value is used by the framework to indicate a unit
was not reported. Drivers should not use this value.

Sensor Names and Classes

When a sensor is created with ksensor_create(9F) it must specify both a
name and a class, which influence how the sensor shows up under
/dev/sensors. The class is a `:' delineated string (the same
conceptually as a minor node's type, see ddi_create_minor_node(9F))
that describes the type of sensor. They begin with "ddi_sensor" and
then are followed by the sensor's kind and then, after another colon,
something that describes what type of hardware it corresponds to. The
framework takes care of defining the class for PCI devices that create
sensors with ksensor_create_scalar_pcidev(9F) and provides the
following classes otherwise:

DDI_NT_SENSOR_TEMP_CPU
Indicates that this is a temperature sensor that relates to the
CPU, whether the socket as a whole, a core, or some other unit.

DDI_NT_SENSOR_TEMP_PCH
Indicates that this is a temperature sensor that relates to an
external chipset to the CPU that is otherwise part of the
platform.

In general, drivers shouldn't create arbitrary classes that aren't
defined by the framework as then they won't be tied into system
services, like topology provided by the fault management architecture.

Where the class effectively indicates the directory structure under
/dev/sensors, the name of the sensor corresponds to the name of the
device that will be created. The semantics of the name determine a bit
on the interface used. While the PCI sensor creation routines are tied
into things such that the name is usually something descriptive, for
other sensors that use ksensor_create(9F), usually the name is part of
a contract with something in userland that will consume it like FMA.

Sensor Creation, Destruction, and Lifetimes
Sensors are tied to an instance of a driver (i.e. a particular
dev_info_t) and are identified through an opaque id_t identifier that
is unique in the system.

To create a ksensor, a driver must call either ksensor_create(9F) or
ksensor_create_scalar_pcidev(9F) in its attach(9E) entry point. A
ksensor cannot be created outside of a driver's attach(9E) entry point.
Once created, the sensor will persist until the driver removes the
sensors with ksensor_remove(9F) which can only be called during
detach(9E) or attach(9E).

As part of creating a ksensor, a driver must supply an operations
vector described in ksensor_ops(9E). This provides both metadata and
data about the sensor itself. The framework provides the following
guarantees and constraints around when the operation vectors will be
called:

+o No ksensor operations registered will ever be called during
attach(9E) and detach(9E).

+o Like with other character devices, if the driver detaches for any
reason (e.g. modunload thread) the character device will be
maintained in /devices and its corresponding symlink in
/dev/sensors. If the device is accessed again, the driver will
automatically be reattached by the system like any other character
device. This alleviates the sensor driver from having to worry
about whether or not it is okay to detach.

+o A single ksensor should assume that its operation vectors will be
called in parallel. That is, not only can both kso_kind(9E) and
kso_scalar(9E) be called from different threads at the same time,
but multiple threads may call a single operation entry point as
well. Put differently, the framework does not intend to serialize
access to a single ksensor.

+o If a driver provides multiple ksensors, it should assume that they
can all be called in parallel. Put differently, different ksensors
can be accessed at the same time.

Kernel versus Userland Processing

The ksensor framework is intended for cases where there are registers
or schemes that can only be accessed by the kernel itself. A good case
of this is where sensors are available through PCI configuration space
or a memory-mapped BAR. Other devices like optical transceivers have
an array of sensors, but are only accessible through an additional I/O
interface like mac_capab_transceiver(9E). In cases where there are a
lot of semantics and parsing required, or the kernel cannot wholly own
the device, it can make more sense to instead leverage a different
interface and allow another part of the system like FMA to amalgamate
the different sensors using additional components in userland.

The right call will vary based on the device and interface. The main
point here is that while the ksensor framework exists, it doesn't have
to be the only way that sensors are provided for consumption. But it
is here to be used where it makes sense!

SEE ALSO

ksensor(4D), attach(9E), detach(9E), ksensor_ops(9E),
ddi_create_minor_node(9F), ksensor_create(9F),
ksensor_create_scalar_pcidev(9F), ksensor_kind(9F)

illumos May 10, 2024 illumos