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:

• No ksensor operations registered will ever be called during attach(9E) and detach(9E).
• 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.
• 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.
• 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!