illumos: manual page: ksensor_create_scalar

KSENSOR_CREATE(9F) Kernel Functions for Drivers KSENSOR_CREATE(9F)

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.