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