1device_contract(4) File Formats device_contract(4)
2
6 device_contract - device contract type
7
9 /system/contract/device
10
13 Device contracts allow processes to monitor events involving a device
14 of interest and to react and/or block state changes involving such
15 devices.
16 Device contracts are managed using the contract(4) file system and the
19 libcontract(3LIB) library. The process contract type directory is /sys‐
20 tem/contract/device.
21 Creation
23 A device contract may be created in one of two ways:
24 o A process may create and activate a template and then invoke
26 open on a minor node of the device. The act of opening cre‐
27 ates a contract based on the terms in the activated tem‐
28 plate.
29 o A process may create a contract after it has opened a device
31 by creating a template, setting appropriate terms (including
32 the path to a minor node) on the template and then invoking
33 ct_tmpl_create() on the template.
34 States, Breaks and Events
36 A state refers to the state of the device which is the subject of the
37 contract. Currently, three states are defined for device contracts:
38 CT_DEV_EV_ONLINE The device is online and functioning normally.
40 CT_DEV_EV_DEGRADED The device is online, but functioning in a
43 degraded capacity.
44 CT_DEV_EV_OFFLINE The device is offline and is not configured for
47 use.
48 A process creates a device contract with the kernel to get a guarantee
52 that the device is in an acceptable set of states as long as the con‐
53 tract is valid. This acceptable set (or "A-set", for short) is speci‐
54 fied as one of the terms of the contract when the contract is created.
55 When a device moves to a state outside the "A-set", the contract is
58 broken. The breaking of the contract may be either asynchronous or syn‐
59 chronous, depending on whether the transition that led to the breaking
60 of the contract is synchronous or asynchronous.
61 If the breaking of a contract is asynchronous, then a critical event is
64 generated and sent to the contract holder. The event is generated even
65 if the contract holder has not subscribed to the event via the critical
66 or informative event sets.
67 If the breaking of the contract is synchronous, a critical contract
70 event is generated with the CTE_NEG flag set to indicate that this is a
71 negotiation event. The contract holder is expected to either acknowl‐
72 edge (ACK) this change and allow the state change to occur or it may
73 negatively acknowledge (NACK) the change to block it (if it has suffi‐
74 cient privileges).
75 The term "event" refers to the transition of a device from one state to
78 another. The event is named by the state to which the device is transi‐
79 tioning. For instance, if a device is transitioning to the OFFLINE
80 state, the name of the event is CT_DEV_EV_OFFLINE. An event may have no
81 consequence for a contract, or it may result in the asynchronous break‐
82 ing of a contract or it may result in a synchronous (that is, negoti‐
83 ated) breaking of a contract. Events are delivered to a contract holder
84 in three cases:
85 o The contract holder has subscribed to the event via the
87 critical or informative event sets. The event may be either
88 critical or informative in this case depending on the sub‐
89 scription.
90 o The device transitions to a state outside the contract's "A-
92 set" and the transition is asynchronous. This results in the
93 asynchronous breaking of the contract and a critical event
94 is delivered to the holder.
95 o The device transitions to a state outside the contract's "A-
97 set" and the transition is synchronous. This results in the
98 synchronous breaking of the contract and a critical event
99 with the CTE_NEG flag set is delivered to the holder.
100 In the last two cases, a critical event is delivered even if the holder
103 has not subscribed to the event via the critical or informative event
104 sets.
105 NEGOTIATION
107 If the breaking of a contract is synchronous, the kernel begins negoti‐
108 ations with the contract holder by generating a critical event before
109 the device changes state. The event has the CTE_NEG flag set indicating
110 that this is a negotiation event. The contract owner is allowed a lim‐
111 ited period of time in which to either ACK the contract event (thus,
112 allowing the state change) or if it has appropriate privileges, NACK
113 the state change (thus, blocking the state change). ACKs may be sent by
114 the holder via ct_ctl_ack(3CONTRACT) and NACKs may be sent via
115 ct_ctl_nack(3CONTRACT). If a contract holder does not send either a
116 NACK or ACK within a specified period of time, an ACK is assumed and
117 the kernel proceeds with the state change.
118 Once the device state change is finalized, the contract subsystem sends
121 negotiation end (NEGEND) critical messages to the contract owner indi‐
122 cating the final disposition of the state transition. That is, either
123 success or failure.
124 Once a contract is broken, a contract owner may choose to create a
127 replacement contract. It may do this after the contract is broken or it
128 may choose to do this synchronously with the breaking of the old con‐
129 tract via ct_ctl_newct(3CONTRACT).
130 TERMS
132 The following common contract terms, defined in contract(4), have
133 device-contract specific attributes:
134 informative set The default value for the informative set is
136 CT_DEV_EV_DEGRADE that is, transitions to the
137 DEGRADED state will by default result in informative
138 events. Use ct_tmpl_set_informative(3CONTRACT) to
139 set this term.
140 critical set The default value for the informative set is
143 CT_DEV_EV_OFFLINE. That is, transitions to the OFF‐
144 LINE state will by default result in critical
145 events. Use ct_tmpl_set_critical(3CONTRACT) to set
146 this term.
147 The following contract terms can be read from or written to a device
151 contract template using the named libcontract(3LIB) interfaces. These
152 contract terms are in addition to those described in contract(4).
153 CTDP_ACCEPT Acceptable set or "A-set".
155 This term is required for every device contract. It
157 defines the set of device states which the contract
158 owner expects to exist as long as the contract is valid.
159 If a device transitions to a state outside this "A-set",
160 then the contract breaks and is no longer valid. A crit‐
161 ical contract event is sent to the contract owner to
162 signal this break.
163 Use ct_dev_tmpl_set_aset() to set this term. The default
165 "A-set" is CT_DEV_EV_ONLINE | CT_DEV_EV_DEGRADE. This
166 term is mandatory. Use ct_dev_tmpl_get_aset() to query a
167 template for this term.
168 CTDP_MINOR Specifies the devfs path to a minor node that is the
171 subject of the contract. Used to specify the minor node
172 to be used for creating a contract when contract cre‐
173 ation takes place other than at open time.
174 If the contract is created synchronously at open(2)
176 time, then this term is implied to be the minor node
177 being opened. In this case, this term need not be
178 explicitly be set.
179 Use ct_dev_tmpl_set_minor() to set this term. The
181 default setting for this term is NULL. That is, no minor
182 node is specified.
183 Use ct_dev_tmpl_get_noneg() to query a template for the
185 setting of this term.
186 CTDP_NONEG If set, this term indicates that any negotiable depar‐
189 ture from the contract terms should be NACKed. That is,
190 the contract subsystem should assume a NACK for any
191 negotiated breaking of the contract. This term is
192 ignored for asynchronous contract breaks.
193 Use ct_dev_tmpl_set_noneg() to set this term. The
195 default setting is off.
196 Use ct_dev_tmpl_get_noneg() to query a template for the
198 setting of this term.
199 STATUS
202 In addition to the standard items, the status object read from a status
203 file descriptor contains the following items if CTD_FIXED is specified:
204 CTDS_STATE Returns the current state of the device. One of the fol‐
206 lowing states is returned:
207 o CT_DEV_EV_ONLINE
209 o CT_DEV_EV_DEGRADED
211 o CT_DEV_EV_OFFLINE
213 Use ct_dev_status_get_dev_state() to obtain
215 this information.
216 CTDS_ASET Returns the acceptable states ("A-set") of the device
219 contract. The return value is a bitset of device states
220 and may include one or more of the following:
221 o CT_DEV_EV_ONLINE
223 o CT_DEV_EV_DEGRADED
225 o CT_DEV_EV_OFFLINE
227 Use ct_dev_status_get_aset() to obtain this
229 information.
230 CTDS_NONEG Returns the current setting of the noneg flag. Returns 1
233 if the noneg flag is set, or 0 if the flag is not set.
234 Use ct_dev_status_get_noneg() to obtain this information.
235 If CTD_ALL is specified, the following items are also available:
239 CTDS_MINOR The devfs path of the device which is the subject of the
241 device contract. Use ct_dev_status_get_minor() to obtain
242 this information.
243 EVENTS
246 No new event related interfaces (beyond the standard contract event
247 interfaces) are defined for device contract events.
248
250 /usr/include/sys/contract/device.h
251 Contains definitions of events, status fields and event fields
253
256 ctrun(1), ctstat(1), ctwatch(1), open(2), ct_tmpl_set_critical(3CON‐
257 TRACT), ct_tmpl_set_informative(3CONTRACT), ct_dev_tmpl_set_aset(3CON‐
258 TRACT), ct_dev_tmpl_get_aset(3CONTRACT), ct_dev_tmpl_set_minor(3CON‐
259 TRACT), ct_dev_tmpl_get_minor(3CONTRACT), ct_dev_tmpl_set_noneg(3CON‐
260 TRACT), ct_dev_tmpl_get_noneg(3CONTRACT), ct_dev_sta‐
261 tus_get_dev_state(3CONTRACT), ct_dev_status_get_aset(3CONTRACT),
262 ct_dev_status_get_minor(3CONTRACT), libcontract(3LIB), contract(4),
263 privileges(5)
264SunOS 5.11 21 Aug 2007 device_contract(4)