1.\" 2.\" This file and its contents are supplied under the terms of the 3.\" Common Development and Distribution License ("CDDL"), version 1.0. 4.\" You may only use this file in accordance with the terms of version 5.\" 1.0 of the CDDL. 6.\" 7.\" A full copy of the text of the CDDL should have accompanied this 8.\" source. A copy of the CDDL is also available via the Internet at 9.\" http://www.illumos.org/license/CDDL. 10.\" 11.\" 12.\" Copyright 2024 Oxide Computer Company 13.\" 14.Dd May 10, 2024 15.Dt KSENSOR 9E 16.Os 17.Sh NAME 18.Nm ksensor 19.Nd kernel sensor framework 20.Sh SYNOPSIS 21.In sys/sensors.h 22.Sh INTERFACE LEVEL 23.Sy Volatile - 24This interface is still evolving in illumos. 25API and ABI stability is not guaranteed. 26.Sh DESCRIPTION 27The ksensor, kernel sensor, framework provides a means for drivers to provide 28various kinds of sensor information to userland such as temperature, voltage, 29current, and control sensors. 30Sensors are exposed in 31.Pa /dev/sensors 32and the framework takes care of managing minor nodes and ioctl interfaces. 33The driver does not need to expose a character device interface nor are its 34minor nodes used. 35.Ss Sensor Types, Kinds, Units and Naming 36Sensors are broken into different types. 37The types describe the shape of the value that can be read from the sensor 38itself. 39Currently, scalar sensors are the only supported sensor type. 40A scalar sensor has several properties: 41.Bl -tag -width Ds 42.It unit : Vt uint32_t 43The unit of the sensor, discussed below, indicates how to interpret the value 44itself. 45.It granularity : Vt int32_t 46The granularity indicates the number of increments per unit in the measurement. 47A value such as 10 indicates that the value is in 10ths of the unit. 48If this was a temperature sensor, one would need to divide by 10 to get the 49value into degrees. 50On the other hand a negative granularity indicates one would need to multiply 51the value to get the actual units. 52For example, a value of -2 would indicate that you'd need to multiply the value 53by two to get the actual number of degrees. 54.It precision : Vt uint32_t 55The precision represents the accuracy of the sensor itself and is measured in 56units of the granularity. 57For example, a temperature sensor that has a granularity of 1, meaning the value 58read from the sensor is in degrees, and is accurate to +/-5 degrees would set 59the precision to 5. 60Conversely, a temperature sensor that measured in 0.5 degree increments has a 61granularity of 2. 62If the sensor was accurate to +/-1 degree, then it'd have a precision of 2. 63If the precision is unknown, it should be left at zero. 64.It value : Vt int64_t 65The value is the actual reading from the sensor and it is interpreted according 66to the granularity. 67This is a signed value as the value may be negative or positive depending on the 68unit. 69.El 70.Pp 71In addition to the type, sensors also have a notion of a kind, which indicates 72what kind of physical property the sensor measures. 73The kernel defines the kinds currently: 74.Bl -tag -width Dv 75.It Dv SENSOR_KIND_TEMPERATURE 76This measures temperature, potentially in degrees Celsius, Fahrenheit, or 77Kelvin. 78This is one of the more common kinds of sensors in the system, as many ASICs 79embed temperature sensors for health and monitoring. 80.It Dv SENSOR_KIND_VOLTAGE 81Voltage sensors measure the amount of voltage at a particular point in a 82circuit. 83This is one part of determining how much power a device is consuming. 84While some ASICs and ICs operate at a fixed voltage range, many support 85operating at diverse ranges and can dynamically vary their voltage. 86.It Dv SENSOR_KIND_CURRENT 87Current sensors measure the total numbers of amps that are passing through 88a measurement point on a circuit 89.Pq which may be indirect . 90This is often a proxy for measuring how much power something is using as many 91computer related electronics operate at a fixed voltage. 92.It Dv SENSOR_KIND_SYNTHETIC 93A synthetic sensor is different from the others in that it does not actually 94measure an actual physical phenomenon. 95Synthetic sensors are generally a unitless measure on some fixed scale. 96That measure is often derived from some actual physical measurement, which is 97why synthetic sensors have the ability to indicate that their measurement is 98derived from another kind of sensor. 99To make this more concrete, let's look at an example. 100.Pp 101The 102.Xr smntemp 4D 103driver exposes the AMD Tctl sensor, which is a control temperature value. 104This is not a measurement in degrees C, but rather is a value from 0 to 100 105where 100 indicates that a thermal shutdown is imminent. 106This value is synthesized and transformed from several different temperature 107samples and goes through its own algorithm, but critically the resulting 108synthetic Tctl sensor does not represent a temperature, but is used to power 109cooling control loops. 110.It Dv SENSOR_KIND_UNKNOWN 111This value is used by the framework to indicate a kind was not reported. 112Drivers should not use this value. 113.El 114.Pp 115From here, a given measurement that occurs also has a unit that is associated 116with it. 117The following sensors are supported: 118.Bl -tag -width Dv 119.It Dv SENSOR_UNIT_CELSIUS 120Indicates that the sensor measure degrees in Celsius 121.Pq C . 122.It Dv SENSOR_UNIT_FAHRENHEIT 123Indicates that the sensor measure degrees in Fahrenheit 124.Pq F . 125.It Dv SENSOR_UNIT_KELVIN 126Indicates that the sensor measure degrees in Kelvin 127.Pq K . 128.It Dv SENSOR_UNIT_VOLTS 129Indicates that the sensor measures voltage in Volts 130.Pq V . 131.It Dv SENSOR_UNIT_AMPS 132Indicates that the sensor measures current in Amperes 133.Pq A . 134.It Dv SENSOR_UNIT_NONE 135This unit indicates that there is no unit because there is associated physical 136property. 137This should be used by 138.Dv SENSOR_KIND_SYNTHETIC 139sensors. 140.It Dv SENSOR_UNIT_UNKNOWN 141This value is used by the framework to indicate a unit was not reported. 142Drivers should not use this value. 143.El 144.Ss Sensor Names and Classes 145When a sensor is created with 146.Xr ksensor_create 9F 147it must specify both a name and a class, which influence how the sensor shows up 148under 149.Pa /dev/sensors. 150The class is a 151.Sq \&: 152delineated string 153.Po 154the same conceptually as a minor node's type, see 155.Xr ddi_create_minor_node 9F 156.Pc 157that describes the type of sensor. 158They begin with 159.Dq ddi_sensor 160and then are followed by the sensor's kind and then, after another colon, 161something that describes what type of hardware it corresponds to. 162The framework takes care of defining the class for PCI devices that create 163sensors with 164.Xr ksensor_create_scalar_pcidev 9F 165and provides the following classes otherwise: 166.Bl -tag -width Ds 167.It Dv DDI_NT_SENSOR_TEMP_CPU 168Indicates that this is a temperature sensor that relates to the CPU, whether the 169socket as a whole, a core, or some other unit. 170.It Dv DDI_NT_SENSOR_TEMP_PCH 171Indicates that this is a temperature sensor that relates to an external chipset 172to the CPU that is otherwise part of the platform. 173.El 174.Pp 175In general, drivers shouldn't create arbitrary classes that aren't defined by 176the framework as then they won't be tied into system services, like topology 177provided by the fault management architecture. 178.Pp 179Where the class effectively indicates the directory structure under 180.Pa /dev/sensors , 181the name of the sensor corresponds to the name of the device that will be 182created. 183The semantics of the name determine a bit on the interface used. 184While the PCI sensor creation routines are tied into things such that the name 185is usually something descriptive, for other sensors that use 186.Xr ksensor_create 9F , 187usually the name is part of a contract with something in userland that will 188consume it like FMA. 189.Ss Sensor Creation, Destruction, and Lifetimes 190Sensors are tied to an instance of a driver 191.Po 192i.e. a particular 193.Vt dev_info_t 194.Pc 195and are identified through an opaque 196.Vt id_t 197identifier that is unique in the system. 198.Pp 199To create a ksensor, a driver must call either 200.Xr ksensor_create 9F 201or 202.Xr ksensor_create_pcidev 9F 203in its 204.Xr attach 9E 205entry point. 206A ksensor cannot be created outside of a driver's 207.Xr attach 9E 208entry point. 209Once created, the sensor will persist until the driver removes the sensors with 210.Xr ksensor_remove 9F 211which can only be called during 212.Xr detach 9E 213or 214.Xr attach 9E . 215.Pp 216As part of creating a ksensor, a driver must supply an operations vector 217described in 218.Xr ksensor_ops 9E . 219This provides both metadata and data about the sensor itself. 220The framework provides the following guarantees and constraints around when the 221operation vectors will be called: 222.Bl -bullet 223.It 224No ksensor operations registered will ever be called during 225.Xr attach 9E 226and 227.Xr detach 9E . 228.It 229Like with other character devices, if the driver detaches for any reason 230.Pq e.g. modunload thread 231the character device will be maintained in 232.Pa /devices 233and its corresponding symlink in 234.Pa /dev/sensors . 235If the device is accessed again, the driver will automatically be reattached by 236the system like any other character device. 237This alleviates the sensor driver from having to worry about whether or not it 238is okay to detach. 239.It 240A single ksensor should assume that its operation vectors will be called in 241parallel. 242That is, not only can both 243.Xr kso_kind 9E 244and 245.Xr kso_scalar 9E 246be called from different threads at the same time, but multiple threads may 247call a single operation entry point as well. 248Put differently, the framework does not intend to serialize access to a single 249ksensor. 250.It 251If a driver provides multiple ksensors, it should assume that they can all be 252called in parallel. 253Put differently, different ksensors can be accessed at the same time. 254.El 255.Ss Kernel versus Userland Processing 256The ksensor framework is intended for cases where there are registers or schemes 257that can only be accessed by the kernel itself. 258A good case of this is where sensors are available through PCI configuration 259space or a memory-mapped BAR. 260Other devices like optical transceivers have an array of sensors, but are only 261accessible through an additional I/O interface like 262.Xr mac_capab_transceiver 9E . 263In cases where there are a lot of semantics and parsing required, or the kernel 264cannot wholly own the device, it can make more sense to instead leverage a 265different interface and allow another part of the system like FMA to amalgamate 266the different sensors using additional components in userland. 267.Pp 268The right call will vary based on the device and interface. 269The main point here is that while the ksensor framework exists, it doesn't have 270to be the only way that sensors are provided for consumption. 271But it is here to be used where it makes sense! 272.Sh SEE ALSO 273.Xr ksensor 4D , 274.Xr attach 9E , 275.Xr detach 9E , 276.Xr ksensor_ops 9E , 277.Xr ddi_create_minor_node 9F , 278.Xr ksensor_create 9F , 279.Xr ksensor_create_scalar_pcidev 9F , 280.Xr ksensor_kind 9F 281