| blob | c6be1742384ab21171c65a65cbb5af8587b1d621 |
1 '\" te
2 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved
3 .\" 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.
4 .\" 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.
5 .\" 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]
6 .TH DEVICE_CONTRACT 4 "Aug 21, 2007"
7 .SH NAME
8 device_contract \- device contract type
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fB/system/contract/device\fR
13 .fi
15 .SH DESCRIPTION
16 .sp
17 .LP
18 Device contracts allow processes to monitor events involving a device of
19 interest and to react and/or block state changes involving such devices.
20 .sp
21 .LP
22 Device contracts are managed using the \fBcontract\fR(4) file system and the
23 \fBlibcontract\fR(3LIB) library. The process contract type directory is
24 \fB/system/contract/device\fR.
25 .SS "Creation"
26 .sp
27 .LP
28 A device contract may be created in one of two ways:
29 .RS +4
30 .TP
31 .ie t \(bu
32 .el o
33 A process may create and activate a template and then invoke open on a minor
34 node of the device. The act of opening creates a contract based on the terms in
35 the activated template.
36 .RE
37 .RS +4
38 .TP
39 .ie t \(bu
40 .el o
41 A process may create a contract after it has opened a device by creating a
42 template, setting appropriate terms (including the path to a minor node) on the
43 template and then invoking \fBct_tmpl_create\fR() on the template.
44 .RE
45 .SS "States, Breaks and Events"
46 .sp
47 .LP
48 A state refers to the state of the device which is the subject of the contract.
49 Currently, three states are defined for device contracts:
50 .sp
51 .ne 2
52 .na
53 \fB\fBCT_DEV_EV_ONLINE\fR\fR
54 .ad
55 .RS 22n
56 The device is online and functioning normally.
57 .RE
59 .sp
60 .ne 2
61 .na
62 \fB\fBCT_DEV_EV_DEGRADED\fR\fR
63 .ad
64 .RS 22n
65 The device is online, but functioning in a degraded capacity.
66 .RE
68 .sp
69 .ne 2
70 .na
71 \fB\fBCT_DEV_EV_OFFLINE\fR\fR
72 .ad
73 .RS 22n
74 The device is offline and is not configured for use.
75 .RE
77 .sp
78 .LP
79 A process creates a device contract with the kernel to get a guarantee that the
80 device is in an acceptable set of states as long as the contract is valid. This
81 acceptable set (or "A-set", for short) is specified as one of the terms of the
82 contract when the contract is created.
83 .sp
84 .LP
85 When a device moves to a state outside the "A-set", the contract is broken. The
86 breaking of the contract may be either asynchronous or synchronous, depending
87 on whether the transition that led to the breaking of the contract is
88 synchronous or asynchronous.
89 .sp
90 .LP
91 If the breaking of a contract is asynchronous, then a critical event is
92 generated and sent to the contract holder. The event is generated even if the
93 contract holder has not subscribed to the event via the critical or informative
94 event sets.
95 .sp
96 .LP
97 If the breaking of the contract is synchronous, a critical contract event is
98 generated with the \fBCTE_NEG\fR flag set to indicate that this is a
99 negotiation event. The contract holder is expected to either acknowledge
100 (\fBACK\fR) this change and allow the state change to occur or it may
101 negatively acknowledge (\fBNACK\fR) the change to block it (if it has
102 sufficient privileges).
103 .sp
104 .LP
105 The term "event" refers to the transition of a device from one state to
106 another. The event is named by the state to which the device is transitioning.
107 For instance, if a device is transitioning to the \fBOFFLINE\fR state, the name
108 of the event is \fBCT_DEV_EV_OFFLINE\fR. An event may have no consequence for a
109 contract, or it may result in the asynchronous breaking of a contract or it may
110 result in a synchronous (that is, negotiated) breaking of a contract. Events
111 are delivered to a contract holder in three cases:
112 .RS +4
113 .TP
114 .ie t \(bu
115 .el o
116 The contract holder has subscribed to the event via the critical or informative
117 event sets. The event may be either critical or informative in this case
118 depending on the subscription.
119 .RE
120 .RS +4
121 .TP
122 .ie t \(bu
123 .el o
124 The device transitions to a state outside the contract's "A-set" and the
125 transition is asynchronous. This results in the asynchronous breaking of the
126 contract and a critical event is delivered to the holder.
127 .RE
128 .RS +4
129 .TP
130 .ie t \(bu
131 .el o
132 The device transitions to a state outside the contract's "A-set" and the
133 transition is synchronous. This results in the synchronous breaking of the
134 contract and a critical event with the \fBCTE_NEG\fR flag set is delivered to
135 the holder.
136 .RE
137 .sp
138 .LP
139 In the last two cases, a critical event is delivered even if the holder has not
140 subscribed to the event via the critical or informative event sets.
141 .SS "NEGOTIATION"
142 .sp
143 .LP
144 If the breaking of a contract is synchronous, the kernel begins negotiations
145 with the contract holder by generating a critical event before the device
146 changes state. The event has the \fBCTE_NEG\fR flag set indicating that this is
147 a negotiation event. The contract owner is allowed a limited period of time in
148 which to either \fBACK\fR the contract event (thus, allowing the state change)
149 or if it has appropriate privileges, \fBNACK\fR the state change (thus,
150 blocking the state change). \fBACK\fRs may be sent by the holder via
151 \fBct_ctl_ack\fR(3CONTRACT) and \fBNACK\fRs may be sent via
152 \fBct_ctl_nack\fR(3CONTRACT). If a contract holder does not send either a
153 \fBNACK\fR or \fBACK\fR within a specified period of time, an \fBACK\fR is
154 assumed and the kernel proceeds with the state change.
155 .sp
156 .LP
157 Once the device state change is finalized, the contract subsystem sends
158 negotiation end (\fBNEGEND\fR) critical messages to the contract owner
159 indicating the final disposition of the state transition. That is, either
160 success or failure.
161 .sp
162 .LP
163 Once a contract is broken, a contract owner may choose to create a replacement
164 contract. It may do this after the contract is broken or it may choose to do
165 this synchronously with the breaking of the old contract via
166 \fBct_ctl_newct\fR(3CONTRACT).
167 .SS "TERMS"
168 .sp
169 .LP
170 The following common contract terms, defined in \fBcontract\fR(4), have
171 device-contract specific attributes:
172 .sp
173 .ne 2
174 .na
175 \fBinformative set\fR
176 .ad
177 .RS 19n
178 The default value for the informative set is \fBCT_DEV_EV_DEGRADE\fR that is,
179 transitions to the \fBDEGRADED\fR state will by default result in informative
180 events. Use \fBct_tmpl_set_informative\fR(3CONTRACT) to set this term.
181 .RE
183 .sp
184 .ne 2
185 .na
186 \fBcritical set\fR
187 .ad
188 .RS 19n
189 The default value for the informative set is \fBCT_DEV_EV_OFFLINE\fR. That is,
190 transitions to the \fBOFFLINE\fR state will by default result in critical
191 events. Use \fBct_tmpl_set_critical\fR(3CONTRACT) to set this term.
192 .RE
194 .sp
195 .LP
196 The following contract terms can be read from or written to a device contract
197 template using the named \fBlibcontract\fR(3LIB) interfaces. These contract
198 terms are in addition to those described in \fBcontract\fR(4).
199 .sp
200 .ne 2
201 .na
202 \fB\fBCTDP_ACCEPT\fR\fR
203 .ad
204 .RS 15n
205 Acceptable set or "A-set".
206 .sp
207 This term is required for every device contract. It defines the set of device
208 states which the contract owner expects to exist as long as the contract is
209 valid. If a device transitions to a state outside this "A-set", then the
210 contract breaks and is no longer valid. A critical contract event is sent to
211 the contract owner to signal this break.
212 .sp
213 Use \fBct_dev_tmpl_set_aset\fR() to set this term. The default "A-set" is
214 \fBCT_DEV_EV_ONLINE\fR | \fBCT_DEV_EV_DEGRADE\fR. This term is mandatory. Use
215 \fBct_dev_tmpl_get_aset\fR() to query a template for this term.
216 .RE
218 .sp
219 .ne 2
220 .na
221 \fB\fBCTDP_MINOR\fR\fR
222 .ad
223 .RS 15n
224 Specifies the \fBdevfs\fR path to a minor node that is the subject of the
225 contract. Used to specify the minor node to be used for creating a contract
226 when contract creation takes place other than at open time.
227 .sp
228 If the contract is created synchronously at \fBopen\fR(2) time, then this term
229 is implied to be the minor node being opened. In this case, this term need not
230 be explicitly be set.
231 .sp
232 Use \fBct_dev_tmpl_set_minor\fR() to set this term. The default setting for
233 this term is \fBNULL\fR. That is, no minor node is specified.
234 .sp
235 Use \fBct_dev_tmpl_get_noneg\fR() to query a template for the setting of this
236 term.
237 .RE
239 .sp
240 .ne 2
241 .na
242 \fB\fBCTDP_NONEG\fR\fR
243 .ad
244 .RS 15n
245 If set, this term indicates that any negotiable departure from the contract
246 terms should be \fBNACK\fRed. That is, the contract subsystem should assume a
247 \fBNACK\fR for any negotiated breaking of the contract. This term is ignored
248 for asynchronous contract breaks.
249 .sp
250 Use \fBct_dev_tmpl_set_noneg\fR() to set this term. The default setting is off.
251 .sp
252 Use \fBct_dev_tmpl_get_noneg\fR() to query a template for the setting of this
253 term.
254 .RE
256 .SS "STATUS"
257 .sp
258 .LP
259 In addition to the standard items, the status object read from a status file
260 descriptor contains the following items if \fBCTD_FIXED\fR is specified:
261 .sp
262 .ne 2
263 .na
264 \fB\fBCTDS_STATE\fR\fR
265 .ad
266 .RS 14n
267 Returns the current state of the device. One of the following states is
268 returned:
269 .RS +4
270 .TP
271 .ie t \(bu
272 .el o
273 \fBCT_DEV_EV_ONLINE\fR
274 .RE
275 .RS +4
276 .TP
277 .ie t \(bu
278 .el o
279 \fBCT_DEV_EV_DEGRADED\fR
280 .RE
281 .RS +4
282 .TP
283 .ie t \(bu
284 .el o
285 \fBCT_DEV_EV_OFFLINE\fR
286 .sp
287 Use \fBct_dev_status_get_dev_state\fR() to obtain this information.
288 .RE
289 .RE
291 .sp
292 .ne 2
293 .na
294 \fB\fBCTDS_ASET\fR\fR
295 .ad
296 .RS 14n
297 Returns the acceptable states ("A-set") of the device contract. The return
298 value is a bitset of device states and may include one or more of the
299 following:
300 .RS +4
301 .TP
302 .ie t \(bu
303 .el o
304 \fBCT_DEV_EV_ONLINE\fR
305 .RE
306 .RS +4
307 .TP
308 .ie t \(bu
309 .el o
310 \fBCT_DEV_EV_DEGRADED\fR
311 .RE
312 .RS +4
313 .TP
314 .ie t \(bu
315 .el o
316 \fBCT_DEV_EV_OFFLINE\fR
317 .sp
318 Use \fBct_dev_status_get_aset\fR() to obtain this information.
319 .RE
320 .RE
322 .sp
323 .ne 2
324 .na
325 \fB\fBCTDS_NONEG\fR\fR
326 .ad
327 .RS 14n
328 Returns the current setting of the \fBnoneg\fR flag. Returns 1 if the
329 \fBnoneg\fR flag is set, or 0 if the flag is not set. Use
330 \fBct_dev_status_get_noneg\fR() to obtain this information.
331 .RE
333 .sp
334 .LP
335 If \fBCTD_ALL\fR is specified, the following items are also available:
336 .sp
337 .ne 2
338 .na
339 \fB\fBCTDS_MINOR\fR\fR
340 .ad
341 .RS 14n
342 The \fBdevfs\fR path of the device which is the subject of the device contract.
343 Use \fBct_dev_status_get_minor\fR() to obtain this information.
344 .RE
346 .SS "EVENTS"
347 .sp
348 .LP
349 No new event related interfaces (beyond the standard contract event interfaces)
350 are defined for device contract events.
351 .SH FILES
352 .sp
353 .ne 2
354 .na
355 \fB\fB/usr/include/sys/contract/device.h\fR\fR
356 .ad
357 .sp .6
358 .RS 4n
359 Contains definitions of events, status fields and event fields
360 .RE
362 .SH SEE ALSO
363 .sp
364 .LP
365 \fBctrun\fR(1), \fBctstat\fR(1), \fBctwatch\fR(1), \fBopen\fR(2),
366 \fBct_tmpl_set_critical\fR(3CONTRACT),
367 \fBct_tmpl_set_informative\fR(3CONTRACT),
368 \fBct_dev_tmpl_set_aset\fR(3CONTRACT), \fBct_dev_tmpl_get_aset\fR(3CONTRACT),
369 \fBct_dev_tmpl_set_minor\fR(3CONTRACT), \fBct_dev_tmpl_get_minor\fR(3CONTRACT),
370 \fBct_dev_tmpl_set_noneg\fR(3CONTRACT), \fBct_dev_tmpl_get_noneg\fR(3CONTRACT),
371 \fBct_dev_status_get_dev_state\fR(3CONTRACT),
372 \fBct_dev_status_get_aset\fR(3CONTRACT),
373 \fBct_dev_status_get_minor\fR(3CONTRACT), \fBlibcontract\fR(3LIB),
374 \fBcontract\fR(4), \fBprivileges\fR(5)