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_CREATE 9F 16.Os 17.Sh NAME 18.Nm ksensor_create , 19.Nm ksensor_create_scalar_pcidev , 20.Nm ksensor_remove 21.Nd create and remove ksensors 22.Sh SYNOPSIS 23.In sys/sensors.h 24.Ft int 25.Fo ksensor_create 26.Fa "dev_info_t *dip" 27.Fa "const ksensor_ops_t *ops" 28.Fa "void *driver" 29.Fa "const char *name" 30.Fa "const char *class" 31.Fa "id_t *idp" 32.Fc 33.Ft int 34.Fo ksensor_create_scalar_pcidev 35.Fa "dev_info_t *dip" 36.Fa "uint64_t kind" 37.Fa "const ksensor_ops_t *ops" 38.Fa "void *driver" 39.Fa "const char *name" 40.Fa "id_t *idp" 41.Fc 42.Ft int 43.Fo ksensor_remove 44.Fa "dev_info_t *dip" 45.Fa "id_t id" 46.Fc 47.Sh INTERFACE LEVEL 48.Sy Volatile - 49This interface is still evolving in illumos. 50API and ABI stability is not guaranteed. 51.Sh PARAMETERS 52.Bl -tag -width Fa 53.It Fa class 54A string that indicates the class of sensor, see 55.Xr ksensor 9E 56for more information. 57.It Fa dip 58Pointer to the driver's 59.Vt dev_info_t 60structure for the specific instance. 61.It Fa driver 62An opaque pointer that will be provided back to the driver in 63.Xr ksensor_ops 9E 64entry points. 65.It Fa id 66A ksensor's ID which can be used to refer back to it in the framework. 67.It Fa idp 68A pointer which will be filled in with a created ksensor's ID. 69.It Fa kind 70A sensor kind, see 71.Xr ksensor 9E 72for a list of kinds. 73.It Fa name 74The name of the ksensor. 75.It Fa ops 76The ksensor operations vector, see 77.Xr ksensor_ops 9E . 78.El 79.Sh DESCRIPTION 80The 81.Fn ksensor_create 82and 83.Fn ksensor_create_scalar_pcidev 84functions are used to create ksensors and register them with the 85.Xr ksensor 9E 86framework during a driver's 87.Xr attach 9E 88entry point. 89A created ksensor is identified by the combination of the driver's 90.Fa dip 91and an ID which is returned in 92.Fa idp , 93which should be kept so the ksensor can be removed via a subsequent call to 94.Fn ksensor_remove . 95.Pp 96The 97.Fn ksensor_create_scalar_pcidev 98function is used to create a ksensor for a PCI or PCIe device and will 99cause it to automatically be registered with the fault management 100architecture. 101.Fa kind 102is one of the sensor kinds listed in 103.Xr ksensor 9E . 104.Pp 105.Fa name 106should be something semantic about what the sensor is or its location in 107the device. 108For example, a voltage or current sensor should try to name the sensor 109based on the rail or supply it measures such as Vdd. 110Similarly, a temperature sensor should try to indicate where it measures 111the temperature. 112.Pp 113The 114.Fa ops 115argument provides the operations vector that the ksensor framework 116should use for making calls. 117The passed in structure must remain valid across the lifetime of the 118ksensor and often is a constant structure in the driver's program text. 119See 120.Xr ksensor_ops 9E 121for more information on the semantics of the callback operations vector. 122These operations vectors will not be called during a driver's 123.Xr attach 9E 124or 125.Xr detach 9E 126entry points, but can otherwise be called in parallel from multiple 127different threads. 128The framework does not provide any serialization. 129.Pp 130The opaque pointer 131.Fa driver , 132will be returned as part of calling any of the 133.Xr ksensor_ops 9E 134entry points. 135As the framework does not provide the corresponding 136.Fa dip 137back in the entry points, this should generally not be a 138.Dv NULL 139pointer. 140.Pp 141The 142.Fn ksensor_create 143function is a more generic function and requires that the driver specify 144the 145.Fa class 146of the sensor directly, rather than having it inferred based upon 147.Fa kind . 148.Pp 149The 150.Fn ksensor_remove 151function allows a driver to remove a ksensor that was previously 152created identified by 153.Fa id . 154To simplify device teardown, a driver may pass the special ID 155.Dv KSENSOR_ALL_IDS 156to remove any registered ksensors. 157Because the framework guarantees that no entry points will be called 158during either 159.Xr attach 9E 160or 161.Xr detach 9E , 162the driver does not need to take special care with when it calls 163.Fn ksensor_remove , 164unlike 165.Xr untimeout 9F . 166.Sh CONTEXT 167The 168.Fn ksensor_create 169and 170.Fn ksensor_create_scalar_pcidev 171functions may only be called from a driver's 172.Xr attach 9E 173entry point. 174The 175.Fn ksensor_remove 176function may only be called from a driver's 177.Xr attach 9E 178or 179.Xr detach 9E 180entry points. 181.Sh RETURN VALUES 182Upon successful completion, the 183.Fn ksensor_create 184and 185.Fn ksensor_create_scalar_pcidev 186functions return 187.Sy 0 188and update 189.Fa idp 190with the newly created ksensor's ID. 191Otherwise, a non-zero error number is returned. 192.Pp 193Upon successful completion, the 194.Fn ksensor_remove 195function returns 196.Sy 0 197and deletes the ksensor. 198Otherwise, a non-zero error number is returned. 199.Sh ERRORS 200The 201.Fn ksensor_create 202and 203.Fn ksensor_create_scalar_pcidev 204functions will fail if: 205.Bl -tag -width Er 206.It Er EAGAIN 207The driver did not call these functions from its 208.Xr attach 9E 209entry point. 210.It Er EEXIST 211A ksensor with the same 212.Fa class 213and 214.Fa name 215already exists. 216.It Er EINVAL 217An invalid pointer was passed or 218.Fa ops , 219.Fa name , 220or 221.Fa class 222are malformed. 223.El 224.Pp 225Additionally, the 226.Fn ksensor_create_scalar_pcidev 227function will fail if: 228.Bl -tag -width Er 229.It Er EINVAL 230.Fa dip 231does not refer to a valid PCI or PCIe device node with a 232.Dq regs 233property. 234.It Er EIO 235The 236.Dq regs 237property of 238.Fa dip 239is malformed. 240.It Er ENOTSUP 241The value of 242.Fa kind 243is not supported. 244.El 245.Pp 246The 247.Fn ksensor_remove 248function will fail if 249.Bl -tag -width Er 250.It Er EAGAIN 251The driver did not call this from either 252.Xr attach 9E 253or 254.Xr detach 9E . 255.It Er ENOENT 256The ksensor referenced in 257.Fa id 258does not exist for 259.Fa dip 260or, if 261.Fa id 262is 263.Dv KSENSOR_ALL_IDS , 264the driver has no ksensors. 265.El 266.Sh SEE ALSO 267.Xr attach 9E , 268.Xr detach 9E , 269.Xr ksensor 9E , 270.Xr ksensor_ops 9E 271