File Formats devicecontract(4)
NAME
devicecontract - 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 sys-
tem 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 appropri-
ate terms (including the path to a minor node) on
the template and then invoking cttmplcreate() on
the template.
States, Breaks and Events
A state refers to the state of the device which is the sub-
ject of the contract. Currently, three states are defined
for device contracts:
CTDEVEVONLINE The device is online and functioning
normally.
CTDEVEVDEGRADED The device is online, but functioning
in a degraded capacity.
CTDEVEVOFLINE The device is offline and is not con-
figured 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
SunOS 5.11 Last change: 21 Aug 2007 1
File Formats devicecontract(4)
"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 con-
tract is broken. The breaking of the contract may be either
asynchronous or synchronous, depending on whether the tran-
sition that led to the breaking of the contract is synchro-
nous or asynchronous.
If the breaking of a contract is asynchronous, then a criti-
cal event is generated and sent to the contract holder. The
event is generated even if the contract holder has not sub-
scribed 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 CTENEG 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 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 transitioning. For instance, if a device
is transitioning to the OFLINE state, the name of the event
is CTDEVEVOFLINE. 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, nego-
tiated) 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 asynchro-
nous. 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 synchro-
nous. This results in the synchronous breaking of
the contract and a critical event with the CTENEG
SunOS 5.11 Last change: 21 Aug 2007 2
File Formats devicecontract(4)
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 CTENEG flag set indicating that this is a negotia-
tion 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
ctctlack(3CONTRACT) and NACKs may be sent via
ctctlnack(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 sub-
system 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 con-
tract is broken or it may choose to do this synchronously
with the breaking of the old contract via
ctctlnewct(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 CTDEVEVDEGRADE that is, transitions
to the DEGRADED state will by default
result in informative events. Use
cttmplsetinformative(3CONTRACT) to set
this term.
critical set The default value for the informative set
is CTDEVEVOFLINE. That is, transi-
tions to the OFLINE state will by
default result in critical events. Use
SunOS 5.11 Last change: 21 Aug 2007 3
File Formats devicecontract(4)
cttmplsetcritical(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).
CTDPACEPT Acceptable set or "A-set".
This term is required for every device con-
tract. 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 ctdevtmplsetaset() to set this term.
The default "A-set" is CTDEVEVONLINE
CTDEVEVDEGRADE. This term is mandatory.
Use ctdevtmplgetaset() to query a tem-
plate for this term.
CTDPMINOR 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 creat-
ing 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 ctdevtmplsetminor() to set this term.
The default setting for this term is NUL.
That is, no minor node is specified.
Use ctdevtmplgetnoneg() to query a tem-
plate for the setting of this term.
CTDPNONEG If set, this term indicates that any negoti-
able 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
SunOS 5.11 Last change: 21 Aug 2007 4
File Formats devicecontract(4)
ignored for asynchronous contract breaks.
Use ctdevtmplsetnoneg() to set this term.
The default setting is off.
Use ctdevtmplgetnoneg() to query a tem-
plate 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 CTDFIXED is specified:
CTDSTATE Returns the current state of the device. One
of the following states is returned:
o CTDEVEVONLINE
o CTDEVEVDEGRADED
o CTDEVEVOFLINE
Use ctdevstatusgetdevstate() to
obtain this information.
CTDSASET 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 CTDEVEVONLINE
o CTDEVEVDEGRADED
o CTDEVEVOFLINE
Use ctdevstatusgetaset() to
obtain this information.
CTDSNONEG 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
ctdevstatusgetnoneg() to obtain this
information.
If CTDAL is specified, the following items are also avail-
able:
SunOS 5.11 Last change: 21 Aug 2007 5
File Formats devicecontract(4)
CTDSMINOR The devfs path of the device which is the sub-
ject of the device contract. Use
ctdevstatusgetminor() to obtain this
information.
EVENTS
No new event related interfaces (beyond the standard con-
tract 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 ALSO
ctrun(1), ctstat(1), ctwatch(1), open(2),
cttmplsetcritical(3CONTRACT),
cttmplsetinformative(3CONTRACT),
ctdevtmplsetaset(3CONTRACT),
ctdevtmplgetaset(3CONTRACT),
ctdevtmplsetminor(3CONTRACT),
ctdevtmplgetminor(3CONTRACT),
ctdevtmplsetnoneg(3CONTRACT),
ctdevtmplgetnoneg(3CONTRACT),
ctdevstatusgetdevstate(3CONTRACT),
ctdevstatusgetaset(3CONTRACT),
ctdevstatusgetminor(3CONTRACT), libcontract(3LIB), con-
tract(4), privileges(5)
SunOS 5.11 Last change: 21 Aug 2007 6
|
