NAME

ksensor_create, ksensor_create_scalar_pcidev, ksensor_remove — create and remove ksensors

SYNOPSIS

#include <sys/sensors.h>

int
ksensor_create(dev_info_t *dip, const ksensor_ops_t *ops, void *driver, const char *name, const char *class, id_t *idp);

int
ksensor_create_scalar_pcidev(dev_info_t *dip, uint64_t kind, const ksensor_ops_t *ops, void *driver, const char *name, id_t *idp);

int
ksensor_remove(dev_info_t *dip, id_t id);

INTERFACE LEVEL

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

PARAMETERS

class: A string that indicates the class of sensor, see ksensor(9E) for more information.
dip: Pointer to the driver's dev_info_t structure for the specific instance.
driver: An opaque pointer that will be provided back to the driver in ksensor_ops(9E) entry points.
id: A ksensor's ID which can be used to refer back to it in the framework.
idp: A pointer which will be filled in with a created ksensor's ID.
kind: A sensor kind, see ksensor(9E) for a list of kinds.
name: The name of the ksensor.
ops: The ksensor operations vector, see ksensor_ops(9E).

DESCRIPTION

The ksensor_create() and ksensor_create_scalar_pcidev() functions are used to create ksensors and register them with the ksensor(9E) framework during a driver's attach(9E) entry point. A created ksensor is identified by the combination of the driver's dip and an ID which is returned in idp, which should be kept so the ksensor can be removed via a subsequent call to ksensor_remove().

The ksensor_create_scalar_pcidev() function is used to create a ksensor for a PCI or PCIe device and will cause it to automatically be registered with the fault management architecture. kind is one of the sensor kinds listed in ksensor(9E).

name should be something semantic about what the sensor is or its location in the device. For example, a voltage or current sensor should try to name the sensor based on the rail or supply it measures such as Vdd. Similarly, a temperature sensor should try to indicate where it measures the temperature.

The ops argument provides the operations vector that the ksensor framework should use for making calls. The passed in structure must remain valid across the lifetime of the ksensor and often is a constant structure in the driver's program text. See ksensor_ops(9E) for more information on the semantics of the callback operations vector. These operations vectors will not be called during a driver's attach(9E) or detach(9E) entry points, but can otherwise be called in parallel from multiple different threads. The framework does not provide any serialization.

The opaque pointer driver, will be returned as part of calling any of the ksensor_ops(9E) entry points. As the framework does not provide the corresponding dip back in the entry points, this should generally not be a NULL pointer.

The ksensor_create() function is a more generic function and requires that the driver specify the class of the sensor directly, rather than having it inferred based upon kind.

The ksensor_remove() function allows a driver to remove a ksensor that was previously created identified by id. To simplify device teardown, a driver may pass the special ID KSENSOR_ALL_IDS to remove any registered ksensors. Because the framework guarantees that no entry points will be called during either attach(9E) or detach(9E), the driver does not need to take special care with when it calls ksensor_remove(), unlike untimeout(9F).

CONTEXT

The ksensor_create() and ksensor_create_scalar_pcidev() functions may only be called from a driver's attach(9E) entry point. The ksensor_remove() function may only be called from a driver's attach(9E) or detach(9E) entry points.

RETURN VALUES

Upon successful completion, the ksensor_create() and ksensor_create_scalar_pcidev() functions return 0 and update idp with the newly created ksensor's ID. Otherwise, a non-zero error number is returned.

Upon successful completion, the ksensor_remove() function returns 0 and deletes the ksensor. Otherwise, a non-zero error number is returned.

ERRORS

The ksensor_create() and ksensor_create_scalar_pcidev() functions will fail if:

EAGAIN: The driver did not call these functions from its attach(9E) entry point.
EEXIST: A ksensor with the same class and name already exists.
EINVAL: An invalid pointer was passed or ops, name, or class are malformed.

Additionally, the ksensor_create_scalar_pcidev() function will fail if:

EINVAL: dip does not refer to a valid PCI or PCIe device node with a “regs” property.
EIO: The “regs” property of dip is malformed.
ENOTSUP: The value of kind is not supported.

The ksensor_remove() function will fail if

EAGAIN: The driver did not call this from either attach(9E) or detach(9E).
ENOENT: The ksensor referenced in id does not exist for dip or, if id is KSENSOR_ALL_IDS, the driver has no ksensors.