illumos: manual page: device

DEVICE_CONTRACT(5) Standards, Environments, and Macros DEVICE_CONTRACT(5)

NAME

device_contract - device contract type

SYNOPSIS

/system/contract/device

DESCRIPTION

Device contracts allow processes to monitor events involving a device of
interest and to react and/or block state changes involving such devices.

Device contracts are managed using the contract(5) file system and the
libcontract(3LIB) library. The process contract type directory is
/system/contract/device.

Creation

A device contract may be created in one of two ways:

o A process may create and activate a template and then invoke
open on a minor node of the device. The act of opening creates
a contract based on the terms in the activated template.

o A process may create a contract after it has opened a device
by creating a template, setting appropriate terms (including
the path to a minor node) on the template and then invoking
ct_tmpl_create() on the template.

States, Breaks and Events
A state refers to the state of the device which is the subject of the
contract. Currently, three states are defined for device contracts:

CT_DEV_EV_ONLINE
The device is online and functioning normally.

CT_DEV_EV_DEGRADED
The device is online, but functioning in a degraded
capacity.

CT_DEV_EV_OFFLINE
The device is offline and is not configured for
use.

A process creates a device contract with the kernel to get a guarantee
that the device is in an acceptable set of states as long as the contract
is valid. This acceptable set (or "A-set", for short) is specified as one
of the terms of the contract when the contract is created.

When a device moves to a state outside the "A-set", the contract is
broken. The breaking of the contract may be either asynchronous or
synchronous, depending on whether the transition that led to the breaking
of the contract is synchronous or asynchronous.

If the breaking of a contract is asynchronous, then a critical event is
generated and sent to the contract holder. The event is generated even if
the contract holder has not subscribed to the event via the critical or
informative event sets.

If the breaking of the contract is synchronous, a critical contract event
is generated with the CTE_NEG flag set to indicate that this is a
negotiation event. The contract holder is expected to either acknowledge
(ACK) this change and allow the state change to occur or it may
negatively acknowledge (NACK) the change to block it (if it has
sufficient privileges).

The term "event" refers to the transition of a device from one state to
another. The event is named by the state to which the device is
transitioning. For instance, if a device is transitioning to the OFFLINE
state, the name of the event is CT_DEV_EV_OFFLINE. An event may have no
consequence for a contract, or it may result in the asynchronous breaking
of a contract or it may result in a synchronous (that is, negotiated)
breaking of a contract. Events are delivered to a contract holder in
three cases:

o The contract holder has subscribed to the event via the
critical or informative event sets. The event may be either
critical or informative in this case depending on the
subscription.

o The device transitions to a state outside the contract's "A-
set" and the transition is asynchronous. This results in the
asynchronous breaking of the contract and a critical event is
delivered to the holder.

o The device transitions to a state outside the contract's "A-
set" and the transition is synchronous. This results in the
synchronous breaking of the contract and a critical event with
the CTE_NEG flag set is delivered to the holder.

In the last two cases, a critical event is delivered even if the holder
has not subscribed to the event via the critical or informative event
sets.

NEGOTIATION

If the breaking of a contract is synchronous, the kernel begins
negotiations with the contract holder by generating a critical event
before the device changes state. The event has the CTE_NEG flag set
indicating that this is a negotiation event. The contract owner is
allowed a limited period of time in which to either ACK the contract
event (thus, allowing the state change) or if it has appropriate
privileges, NACK the state change (thus, blocking the state change). ACKs
may be sent by the holder via ct_ctl_ack(3CONTRACT) and NACKs may be sent
via ct_ctl_nack(3CONTRACT). If a contract holder does not send either a
NACK or ACK within a specified period of time, an ACK is assumed and the
kernel proceeds with the state change.

Once the device state change is finalized, the contract subsystem sends
negotiation end (NEGEND) critical messages to the contract owner
indicating the final disposition of the state transition. That is, either
success or failure.

Once a contract is broken, a contract owner may choose to create a
replacement contract. It may do this after the contract is broken or it
may choose to do this synchronously with the breaking of the old contract
via ct_ctl_newct(3CONTRACT).

TERMS

The following common contract terms, defined in contract(5), have device-
contract specific attributes:

informative set
The default value for the informative set is
CT_DEV_EV_DEGRADE that is, transitions to the DEGRADED
state will by default result in informative events.
Use ct_tmpl_set_informative(3CONTRACT) to set this
term.

critical set
The default value for the informative set is
CT_DEV_EV_OFFLINE. That is, transitions to the OFFLINE
state will by default result in critical events. Use
ct_tmpl_set_critical(3CONTRACT) to set this term.

The following contract terms can be read from or written to a device
contract template using the named libcontract(3LIB) interfaces. These
contract terms are in addition to those described in contract(5).

CTDP_ACCEPT
Acceptable set or "A-set".

This term is required for every device contract. It
defines the set of device states which the contract owner
expects to exist as long as the contract is valid. If a
device transitions to a state outside this "A-set", then
the contract breaks and is no longer valid. A critical
contract event is sent to the contract owner to signal
this break.

Use ct_dev_tmpl_set_aset() to set this term. The default
"A-set" is CT_DEV_EV_ONLINE | CT_DEV_EV_DEGRADE. This term
is mandatory. Use ct_dev_tmpl_get_aset() to query a
template for this term.

CTDP_MINOR
Specifies the devfs path to a minor node that is the
subject of the contract. Used to specify the minor node to
be used for creating a contract when contract creation
takes place other than at open time.

If the contract is created synchronously at open(2) time,
then this term is implied to be the minor node being
opened. In this case, this term need not be explicitly be
set.

Use ct_dev_tmpl_set_minor() to set this term. The default
setting for this term is NULL. That is, no minor node is
specified.

Use ct_dev_tmpl_get_noneg() to query a template for the
setting of this term.

CTDP_NONEG
If set, this term indicates that any negotiable departure
from the contract terms should be NACKed. That is, the
contract subsystem should assume a NACK for any negotiated
breaking of the contract. This term is ignored for
asynchronous contract breaks.

Use ct_dev_tmpl_set_noneg() to set this term. The default
setting is off.

Use ct_dev_tmpl_get_noneg() to query a template for the
setting of this term.

STATUS

In addition to the standard items, the status object read from a status
file descriptor contains the following items if CTD_FIXED is specified:

CTDS_STATE
Returns the current state of the device. One of the
following states is returned:

o CT_DEV_EV_ONLINE

o CT_DEV_EV_DEGRADED

o CT_DEV_EV_OFFLINE

Use ct_dev_status_get_dev_state() to obtain this
information.

CTDS_ASET
Returns the acceptable states ("A-set") of the device
contract. The return value is a bitset of device states and
may include one or more of the following:

o CT_DEV_EV_ONLINE

o CT_DEV_EV_DEGRADED

o CT_DEV_EV_OFFLINE

Use ct_dev_status_get_aset() to obtain this
information.

CTDS_NONEG
Returns the current setting of the noneg flag. Returns 1 if
the noneg flag is set, or 0 if the flag is not set. Use
ct_dev_status_get_noneg() to obtain this information.

If CTD_ALL is specified, the following items are also available:

CTDS_MINOR
The devfs path of the device which is the subject of the
device contract. Use ct_dev_status_get_minor() to obtain
this information.

EVENTS

No new event related interfaces (beyond the standard contract event
interfaces) are defined for device contract events.

FILES

/usr/include/sys/contract/device.h

Contains definitions of events, status fields and event fields