'\" te
.\"  Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH DEVICE_CONTRACT 5 "Aug 21, 2007"
.SH NAME
device_contract \- device contract type
.SH SYNOPSIS
.LP
.nf
\fB/system/contract/device\fR
.fi

.SH DESCRIPTION
.sp
.LP
Device contracts allow processes to monitor events involving a device of
interest and to react and/or block state changes involving such devices.
.sp
.LP
Device contracts are managed using the \fBcontract\fR(5) file system and the
\fBlibcontract\fR(3LIB) library. The process contract type directory is
\fB/system/contract/device\fR.
.SS "Creation"
.sp
.LP
A device contract may be created in one of two ways:
.RS +4
.TP
.ie t \(bu
.el 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.
.RE
.RS +4
.TP
.ie t \(bu
.el 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 \fBct_tmpl_create\fR() on the template.
.RE
.SS "States, Breaks and Events"
.sp
.LP
A state refers to the state of the device which is the subject of the contract.
Currently, three states are defined for device contracts:
.sp
.ne 2
.na
\fB\fBCT_DEV_EV_ONLINE\fR\fR
.ad
.RS 22n
The device is online and functioning normally.
.RE

.sp
.ne 2
.na
\fB\fBCT_DEV_EV_DEGRADED\fR\fR
.ad
.RS 22n
The device is online, but functioning in a degraded capacity.
.RE

.sp
.ne 2
.na
\fB\fBCT_DEV_EV_OFFLINE\fR\fR
.ad
.RS 22n
The device is offline and is not configured for use.
.RE

.sp
.LP
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.
.sp
.LP
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.
.sp
.LP
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.
.sp
.LP
If the breaking of the contract is synchronous, a critical contract event is
generated with the \fBCTE_NEG\fR flag set to indicate that this is a
negotiation event. The contract holder is expected to either acknowledge
(\fBACK\fR) this change and allow the state change to occur or it may
negatively acknowledge (\fBNACK\fR) the change to block it (if it has
sufficient privileges).
.sp
.LP
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 \fBOFFLINE\fR state, the name
of the event is \fBCT_DEV_EV_OFFLINE\fR. 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:
.RS +4
.TP
.ie t \(bu
.el 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.
.RE
.RS +4
.TP
.ie t \(bu
.el 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.
.RE
.RS +4
.TP
.ie t \(bu
.el 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 \fBCTE_NEG\fR flag set is delivered to
the holder.
.RE
.sp
.LP
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.
.SS "NEGOTIATION"
.sp
.LP
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 \fBCTE_NEG\fR flag set indicating that this is
a negotiation event. The contract owner is allowed a limited period of time in
which to either \fBACK\fR the contract event (thus, allowing the state change)
or if it has appropriate privileges, \fBNACK\fR the state change (thus,
blocking the state change). \fBACK\fRs may be sent by the holder via
\fBct_ctl_ack\fR(3CONTRACT) and \fBNACK\fRs may be sent via
\fBct_ctl_nack\fR(3CONTRACT). If a contract holder does not send either a
\fBNACK\fR or \fBACK\fR within a specified period of time, an \fBACK\fR is
assumed and the kernel proceeds with the state change.
.sp
.LP
Once the device state change is finalized, the contract subsystem sends
negotiation end (\fBNEGEND\fR) critical messages to the contract owner
indicating the final disposition of the state transition. That is, either
success or failure.
.sp
.LP
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
\fBct_ctl_newct\fR(3CONTRACT).
.SS "TERMS"
.sp
.LP
The following common contract terms, defined in \fBcontract\fR(5), have
device-contract specific attributes:
.sp
.ne 2
.na
\fBinformative set\fR
.ad
.RS 19n
The default value for the informative set is \fBCT_DEV_EV_DEGRADE\fR that is,
transitions to the \fBDEGRADED\fR state will by default result in informative
events. Use \fBct_tmpl_set_informative\fR(3CONTRACT) to set this term.
.RE

.sp
.ne 2
.na
\fBcritical set\fR
.ad
.RS 19n
The default value for the informative set is \fBCT_DEV_EV_OFFLINE\fR. That is,
transitions to the \fBOFFLINE\fR state will by default result in critical
events. Use \fBct_tmpl_set_critical\fR(3CONTRACT) to set this term.
.RE

.sp
.LP
The following contract terms can be read from or written to a device contract
template using the named \fBlibcontract\fR(3LIB) interfaces. These contract
terms are in addition to those described in \fBcontract\fR(5).
.sp
.ne 2
.na
\fB\fBCTDP_ACCEPT\fR\fR
.ad
.RS 15n
Acceptable set or "A-set".
.sp
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.
.sp
Use \fBct_dev_tmpl_set_aset\fR() to set this term. The default "A-set" is
\fBCT_DEV_EV_ONLINE\fR | \fBCT_DEV_EV_DEGRADE\fR. This term is mandatory. Use
\fBct_dev_tmpl_get_aset\fR() to query a template for this term.
.RE

.sp
.ne 2
.na
\fB\fBCTDP_MINOR\fR\fR
.ad
.RS 15n
Specifies the \fBdevfs\fR 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.
.sp
If the contract is created synchronously at \fBopen\fR(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.
.sp
Use \fBct_dev_tmpl_set_minor\fR() to set this term. The default setting for
this term is \fBNULL\fR. That is, no minor node is specified.
.sp
Use \fBct_dev_tmpl_get_noneg\fR() to query a template for the setting of this
term.
.RE

.sp
.ne 2
.na
\fB\fBCTDP_NONEG\fR\fR
.ad
.RS 15n
If set, this term indicates that any negotiable departure from the contract
terms should be \fBNACK\fRed. That is, the contract subsystem should assume a
\fBNACK\fR for any negotiated breaking of the contract. This term is ignored
for asynchronous contract breaks.
.sp
Use \fBct_dev_tmpl_set_noneg\fR() to set this term. The default setting is off.
.sp
Use \fBct_dev_tmpl_get_noneg\fR() to query a template for the setting of this
term.
.RE

.SS "STATUS"
.sp
.LP
In addition to the standard items, the status object read from a status file
descriptor contains the following items if \fBCTD_FIXED\fR is specified:
.sp
.ne 2
.na
\fB\fBCTDS_STATE\fR\fR
.ad
.RS 14n
Returns the current state of the device. One of the following states is
returned:
.RS +4
.TP
.ie t \(bu
.el o
\fBCT_DEV_EV_ONLINE\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBCT_DEV_EV_DEGRADED\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBCT_DEV_EV_OFFLINE\fR
.sp
Use \fBct_dev_status_get_dev_state\fR() to obtain this information.
.RE
.RE

.sp
.ne 2
.na
\fB\fBCTDS_ASET\fR\fR
.ad
.RS 14n
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:
.RS +4
.TP
.ie t \(bu
.el o
\fBCT_DEV_EV_ONLINE\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBCT_DEV_EV_DEGRADED\fR
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBCT_DEV_EV_OFFLINE\fR
.sp
Use \fBct_dev_status_get_aset\fR() to obtain this information.
.RE
.RE

.sp
.ne 2
.na
\fB\fBCTDS_NONEG\fR\fR
.ad
.RS 14n
Returns the current setting of the \fBnoneg\fR flag. Returns 1 if the
\fBnoneg\fR flag is set, or 0 if the flag is not set. Use
\fBct_dev_status_get_noneg\fR() to obtain this information.
.RE

.sp
.LP
If \fBCTD_ALL\fR is specified, the following items are also available:
.sp
.ne 2
.na
\fB\fBCTDS_MINOR\fR\fR
.ad
.RS 14n
The \fBdevfs\fR path of the device which is the subject of the device contract.
Use \fBct_dev_status_get_minor\fR() to obtain this information.
.RE

.SS "EVENTS"
.sp
.LP
No new event related interfaces (beyond the standard contract event interfaces)
are defined for device contract events.
.SH FILES
.sp
.ne 2
.na
\fB\fB/usr/include/sys/contract/device.h\fR\fR
.ad
.sp .6
.RS 4n
Contains definitions of events, status fields and event fields
.RE

.SH SEE ALSO
.sp
.LP
.BR ctrun (1),
.BR ctstat (1),
.BR ctwatch (1),
.BR open (2),
.BR ct_dev_status_get_aset (3CONTRACT),
.BR ct_dev_status_get_dev_state (3CONTRACT),
.BR ct_dev_status_get_minor (3CONTRACT),
.BR ct_dev_tmpl_get_aset (3CONTRACT),
.BR ct_dev_tmpl_get_minor (3CONTRACT),
.BR ct_dev_tmpl_get_noneg (3CONTRACT),
.BR ct_dev_tmpl_set_aset (3CONTRACT),
.BR ct_dev_tmpl_set_minor (3CONTRACT),
.BR ct_dev_tmpl_set_noneg (3CONTRACT),
.BR ct_tmpl_set_critical (3CONTRACT),
.BR ct_tmpl_set_informative (3CONTRACT),
.BR libcontract (3LIB),
.BR contract (5),
.BR privileges (7)