Tribblix: manual page: device

DEVICE_CONTRACT(5) File Formats and Configurations 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