Tribblix: manual page: ksensor

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.