device_contract(4) File Formats device_contract(4)NAMEdevice_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(4) file system and the
libcontract(3LIB) library. The process contract type directory is /sys‐
tem/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 cre‐
ates a contract based on the terms in the activated tem‐
plate.
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 con‐
tract is valid. This acceptable set (or "A-set", for short) is speci‐
fied 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 syn‐
chronous, 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 acknowl‐
edge (ACK) this change and allow the state change to occur or it may
negatively acknowledge (NACK) the change to block it (if it has suffi‐
cient 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 transi‐
tioning. 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 break‐
ing of a contract or it may result in a synchronous (that is, negoti‐
ated) 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 sub‐
scription.
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 negoti‐
ations 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 lim‐
ited 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 indi‐
cating 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 con‐
tract via ct_ctl_newct(3CONTRACT).
TERMS
The following common contract terms, defined in contract(4), 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 OFF‐
LINE 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(4).
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 crit‐
ical 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 cre‐
ation 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 depar‐
ture 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 fol‐
lowing 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
SEE ALSOctrun(1), ctstat(1), ctwatch(1), open(2), ct_tmpl_set_critical(3CON‐
TRACT), ct_tmpl_set_informative(3CONTRACT), ct_dev_tmpl_set_aset(3CON‐
TRACT), ct_dev_tmpl_get_aset(3CONTRACT), ct_dev_tmpl_set_minor(3CON‐
TRACT), ct_dev_tmpl_get_minor(3CONTRACT), ct_dev_tmpl_set_noneg(3CON‐
TRACT), ct_dev_tmpl_get_noneg(3CONTRACT), ct_dev_sta‐
tus_get_dev_state(3CONTRACT), ct_dev_status_get_aset(3CONTRACT),
ct_dev_status_get_minor(3CONTRACT), libcontract(3LIB), contract(4),
privileges(5)SunOS 5.11 21 Aug 2007 device_contract(4)