| blob | dda52516f54c72131bc5142a02b7ada538a82f28 |
1 '\" te
2 .\" Copyright (c) 2006, 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 LIBPOOL 3LIB "Dec 14, 2006"
7 .SH NAME
8 libpool \- pool configuration manipulation library
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ]
13 #include <\fBpool.h\fR>
14 .fi
16 .SH DESCRIPTION
17 .sp
18 .LP
19 The functions in this library define the interface for reading and writing
20 resource pools configuration files, as well as that for commiting an existing
21 configuration to becoming the running OS configuration (with respect to
22 partitioning subsystems). The <\fBpool.h\fR> header provides type and function
23 declarations for all library services.
24 .sp
25 .LP
26 The resource pools facility brings together process-bindable resources into a
27 common abstraction called a pool. Processor sets and other entities can be
28 configured, grouped, and labelled in a persistent fashion such that workload
29 components can be associated with a subset of a system's total resources. The
30 \fBlibpool\fR library provides a C language API for accessing this
31 functionality, while \fBpooladm\fR(1M), \fBpoolbind\fR(1M), and
32 \fBpoolcfg\fR(1M) make this facility available through command invocations from
33 a shell. Each of those manual pages describes aspects of the pools facility;
34 this page describes the properties available to the various entities managed
35 within the pools facility. These entities include the system, pools, and the
36 \fBpset\fR resources for processor sets.
37 .sp
38 .LP
39 When the pools facility is enabled on a system, the behavior of the following
40 functions is modified.
41 .sp
43 .sp
44 .TS
45 c c
46 l l .
47 System Call Error Value
48 _
49 \fBpset_assign\fR(pset !=\fBPS_QUERY\fR) \fBENOTSUP\fR
50 \fBpset_bind\fR(pset !=\fBPS_QUERY\fR) \fBENOTSUP\fR
51 \fBpset_create()\fR \fBENOTSUP\fR
52 \fBpset_destroy()\fR \fBENOTSUP\fR
53 \fBpset_setattr()\fR \fBENOTSUP\fR
54 .TE
56 .sp
57 .LP
58 Each active entity within the resource pools framework can have an arbitrary
59 collection of named, typed properties associated with it. Properties supported
60 by the pools framework are listed, with descriptions, under each entity below.
61 In general, resource properties can be one of five types: boolean (\fBbool\fR),
62 signed (\fBint64\fR) and unsigned (\fBuint64\fR) integers, floating point
63 (\fBdouble\fR), and \fBstring\fR values.
64 .sp
65 .LP
66 All entities and resources support a string property for commenting purposes;
67 this property is available for use by management applications to record
68 descriptions and other administrator oriented data. The comment field is not
69 used by the default pools commands, except when a configuration is initiated by
70 the \fBpoolcfg\fR utility, in which case an informative message is placed in
71 the \fBsystem.comment\fR property for that configuration.
72 .SS "System"
73 .sp
75 .sp
76 .TS
77 c c c
78 l l l .
79 Property name Type Description
80 \fBsystem.allocate-method\fR \fBstring\fR T{
81 Allocation method to use when this configuration is instantiated
82 T}
83 \fBsystem.bind-default\fR \fBbool\fR T{
84 If specified pool not found, bind to pool with 'pool.default' property set to true
85 T}
86 \fBsystem.comment\fR \fBstring\fR User description of system
87 \fBsystem.name\fR \fBstring\fR User name for the configuration
88 \fBsystem.version\fR \fBint64\fR T{
89 \fBlibpool\fR version required to manipulate this configuration
90 T}
91 \fBsystem.poold.log-level\fR \fBstring\fR \fBpoold\fR logging level
92 \fBsystem.poold.log-location\fR \fBstring\fR \fBpoold\fR logging location
93 \fBsystem.poold.history-file\fR \fBstring\fR \fBpoold\fR decision history location
94 \fBsystem.poold.monitor-interval\fR \fBuint64\fR \fBpoold\fR monitoring sample interval
95 \fBsystem.poold.objectives\fR \fBstring\fR \fBpoold\fR objectives for a system.
96 .TE
98 .sp
99 .LP
100 The \fBsystem.allocate-method\fR, \fBsystem.bind-default\fR,
101 \fBsystem.comment\fR, \fBsystem.name\fR, \fBsystem.poold.log-level\fR,
102 \fBsystem.poold.log-location\fR, \fBsystem.poold.history-file\fR,
103 \fBsystem.poold.monitor-interval\fR, and \fBsystem.poold.objectives\fR
104 properties are writable; the \fBsystem.version\fR property is not.
105 .sp
106 .LP
107 The \fBsystem.allocate-method\fR property accepts only two values, "importance
108 based" and "surplus to default". The default value for this property is
109 "importance based". The property is optional and if it is not present the
110 library will allocate resources as though it were present and had the default
111 value. These strings are defined in <\fBpool.h\fR> as \fBPOA_IMPORTANCE\fR and
112 \fBPOA_SURPLUS_TO_DEFAULT\fR.
113 .sp
114 .LP
115 If "importance based" allocation is defined, then during a commit the library
116 will allocate resources to pools using an algorithm that observes minimum and
117 maximum constraints for resources but favors those resources with greater
118 importance.
119 .sp
120 .LP
121 If "surplus to default" is defined, then during a commit the library will
122 allocate minimum resources to all resource sets apart from default which will
123 receive any surplus.
124 .sp
125 .LP
126 The \fBsystem.bind-default\fR property defaults to true. This property
127 interacts with the \fBproject.pool\fR resource control to specify the binding
128 behavior for processes associated with a project. If \fBproject.pool\fR is not
129 specified, then this property has no effect. If \fBproject.pool\fR is specified
130 and the specified pool exists, this property has no effect. If the specified
131 pool does not exist, perhaps because of a reconfiguration, then this property
132 controls the binding behavior for the project member. If
133 \fBsystem.bind-default\fR is true, then the project member is bound to the
134 default pool (identified as the pool for which \fBpool.default\fR is true);
135 otherise the project member is refused access to the system. Care should be
136 taken with the pools configuration if this property is set to false, so as to
137 avoid denying users access to the system.
138 .sp
139 .LP
140 The various \fBpoold\fR properties are used to configure the operation of
141 \fBpoold\fR(1M).
142 .sp
143 .LP
144 The \fBsystem.poold.log-level\fR property is used to specify the level of
145 detail provided in log messages. Valid values are: \fBALERT\fR, \fBCRIT\fR,
146 \fBERR\fR, \fBWARNING\fR, \fBNOTICE\fR, \fBINFO\fR, and \fBDEBUG\fR.
147 .sp
148 .LP
149 \fBALERT\fR provides the least level of detail, \fBDEBUG\fR the greatest. See
150 \fBsyslog\fR(3C) for more information about the meaning of these debug levels.
151 If this property is not specified, the default value \fBNOTICE\fR is used.
152 .sp
153 .LP
154 The \fBsystem.poold.log-location\fR property is used to specify the location of
155 the logfiles generated by \fBpoold\fR. The special value of "syslog" indicates
156 that logged messages should be written to \fBsyslog()\fR. If this property is
157 not specified, the default location \fB/var/log/pool\fR is used.
158 .sp
159 .LP
160 The \fBsystem.poold.history-file\fR specifies the location of the decision
161 history file which is used by \fBpoold\fR to improve the quality of its
162 decision making over time. If this property is not specified, the default
163 location \fB/var/adm/pool\fR is used.
164 .sp
165 .LP
166 The \fBsystem.poold.monitor-interval\fR property specifies the monitoring
167 interval (in milliseconds) to be used by \fBpoold\fR when sampling utilization
168 statistics. If this property is not specified, the default value of 15 seconds
169 is used.
170 .sp
171 .LP
172 The \fBsystem.poold.objectives\fR property specifies any system wide
173 objectives. An objectives property has the following syntax:
174 .sp
175 .in +2
176 .nf
177 objectives = objective [; objective]*
178 objective = [n:] keyword [op] [value]
179 .fi
180 .in -2
182 .sp
183 .LP
184 All objectives are prefixed with an optional importance. The importance acts as
185 a multiplier for the objective and thus increases the significance of its
186 contribution to the objective function evaluation. If no importance is
187 specified, the default value is 1.
188 .sp
189 .LP
190 The "wt-load" objective is the only objective to which a system element can be
191 set. This objective favors configurations that match resource allocations to
192 resource utilization. A resource set that uses more resources will be given
193 more resources when this objective is active. An administrator should use this
194 objective when he is relatively satisfied with the constraints established
195 using the minimum and maximum properties and would like the DRP to manipulate
196 resources freely within those constraints.
197 .SS "Pools"
198 .sp
200 .sp
201 .TS
202 c c c
203 l l l .
204 Property name Type Description
205 \fBpool.active\fR \fBbool\fR Mark this pool as active, if true.
206 \fBpool.comment\fR \fBstring\fR User description of pool.
207 \fBpool.default\fR \fBbool\fR T{
208 Mark this pool as the default pool, if true; see system.bind-default property.
209 T}
210 \fBpool.importance\fR \fBint64\fR T{
211 Relative importance of this pool; for possible resource dispute resolution.
212 T}
213 \fBpool.name\fR \fBstring\fR T{
214 User name for pool; used by \fBsetproject\fR(3PROJECT) as value for 'project.pool' project attribute in \fBproject\fR(4) database.
215 T}
216 \fBpool.scheduler\fR \fBstring\fR T{
217 Scheduler class to which consumers of this pool will be bound. This property is optional and if not specified, the scheduler bindings for consumers of this pool are not affected.
218 T}
219 \fBpool.sys_id\fR \fBint64\fR System-assigned pool ID.
220 \fBpool.temporary\fR \fBbool\fR T{
221 Mark this pool as a temporary resource; if true, this pool can exist only in the dynamic configuration and cannot be committed to a configuration file.
222 T}
223 .TE
225 .sp
226 .LP
227 The \fBpool.default\fR, \fBpool.sys_id\fR, and \fBpool.temporary\fR properties
228 are not writable; all other listed properties are writable.
229 .sp
230 .LP
231 If pool.scheduler is specified, it must be set to the name of a valid
232 scheduling class for the system. See the \fB-c\fR option for \fBpriocntl\fR(1)
233 for a list of valid class names.
234 .SS "Processor Sets"
235 .sp
237 .sp
238 .TS
239 c c c
240 l l l .
241 Property name Type Description
242 \fBpset.comment\fR \fBstring\fR User description of resource.
243 \fBpset.default\fR \fBbool\fR Marks default processor set.
244 \fBpset.load\fR \fBuint64\fR The load for this processor set.
245 \fBpset.max\fR \fBuint64\fR T{
246 Maximum number of CPUs permitted in this processor set.
247 T}
248 \fBpset.min\fR \fBuint64\fR T{
249 Minimum number of CPUs permitted in this processor set.
250 T}
251 \fBpset.name\fR \fBstring\fR User name for resource.
252 \fBpset.size\fR \fBuint64\fR T{
253 Current number of CPUs in this processor set.
254 T}
255 \fBpset.sys_id\fR \fBint64\fR System-assigned processor set ID.
256 \fBpset.temporary\fR \fBbool\fR T{
257 Mark this processor set as a temporary resource; if true, this processor set can exist only in the dynamic configuration and cannot be committed to a configuration file.
258 T}
259 \fBpset.type\fR \fBstring\fR T{
260 Names resource type; value for all processor sets is \fBpset\fR.
261 T}
262 \fBpset.units\fR \fBstring\fR T{
263 Identifies meaning of size-related properties; value for all processor sets is \fBpopulation\fR.
264 T}
265 \fBpset.poold.objectives\fR \fBstring\fR T{
266 Specifies the poold objectives for a pset.
267 T}
268 .TE
270 .sp
271 .LP
272 The \fBpset.comment\fR, \fBpset.max\fR, \fBpset.min\fR, \fBpset.name\fR, and
273 \fBpset.poold.objectives\fR properties are writable; the \fBpset.default\fR,
274 \fBpset.load\fR, \fBpset.size\fR, \fBpset.sys_id\fR, \fBpset.temporary\fR,
275 \fBpset.type\fR, and \fBpset.units\fR properties are not.
276 .sp
277 .LP
278 The \fBpset.load\fR property represents the load on a processor set. The lowest
279 value for this property is 0. The value of \fBpset.load\fR increases in a
280 linear fashion with the load on the set, as measured by the number of jobs in
281 the system run queue.
282 .sp
283 .LP
284 The \fBpset.poold.objectives\fR property specifies an objective which is
285 specific to a particular \fBpset\fR. See the \fBsystem.poold.objectives\fR
286 entry for the specification of this property's syntax.
287 .sp
288 .LP
289 There are two types of objectives that can be set on a \fBpset\fR:
290 .sp
291 .ne 2
292 .na
293 \fB\fBlocality\fR\fR
294 .ad
295 .RS 15n
296 This objective influences the impact that locality, as measured by lgroup data,
297 has upon the chosen configuration. This objective can take one of three values:
298 .sp
299 .ne 2
300 .na
301 \fB\fBtight\fR\fR
302 .ad
303 .RS 9n
304 If set, configurations that maximize resource locality are favored.
305 .RE
307 .sp
308 .ne 2
309 .na
310 \fB\fBloose\fR\fR
311 .ad
312 .RS 9n
313 If set, configurations that minimize resource locality are favored.
314 .RE
316 .sp
317 .ne 2
318 .na
319 \fB\fBnone\fR\fR
320 .ad
321 .RS 9n
322 This is the default value for this objective. If set, configuration
323 favorability is uninfluenced by resource locality.
324 .RE
326 .RE
328 .sp
329 .ne 2
330 .na
331 \fB\fButilization\fR\fR
332 .ad
333 .RS 15n
334 This objective favors configurations that allocate resources to partitions that
335 are failing to preserve the specified utilization objective.
336 .RE
338 .sp
339 .LP
340 These objectives are specified in terms of an operator and a value. The
341 operators are
342 .sp
343 .ne 2
344 .na
345 \fB\fB<\fR\fR
346 .ad
347 .RS 5n
348 The ``less than'' operator is used to indicate that the specified value should
349 be treated as a maximum target value.
350 .RE
352 .sp
353 .ne 2
354 .na
355 \fB\fB>\fR\fR
356 .ad
357 .RS 5n
358 The ``greater than'' operator is used to indicate that the specified value
359 should be treated as a minimum target value.
360 .RE
362 .sp
363 .ne 2
364 .na
365 \fB\fB~\fR\fR
366 .ad
367 .RS 5n
368 The ``about'' operator is used to indicate that the specified value should be
369 treated as a target value about which some fluctuation is acceptable.
370 .RE
372 .sp
373 .LP
374 Only one objective of each type of operator can be set. For example, if the
375 \fB~\fR operator is set, the \fB<\fR and \fB>\fR operators cannot be set. It is
376 possible to set a \fB<\fR and a \fB>\fR operator together; the values will be
377 validated to ensure that they do not overlap.
378 .SS "Processors"
379 .sp
381 .sp
382 .TS
383 c c c
384 l l l .
385 Property name Type Description
386 _
387 \fBcpu.comment\fR \fBstring\fR User description of CPU.
388 \fBcpu.pinned\fR \fBbool\fR CPU pinned to this processor set.
389 \fBcpu.status\fR \fBint64\fR T{
390 Processor status, on-line, offline or interrupts disabled.
391 T}
392 \fBcpu.sys_id\fR \fBint64\fR System-assigned processor ID.
393 .TE
395 .sp
396 .LP
397 The \fBcpu.comment\fR, \fBcpu.pinned\fR, and \fBcpu.status\fR properties are
398 writeable.
399 .sp
400 .LP
401 The \fBcpu.status\fR property can be set only to the following values:
402 .sp
403 .ne 2
404 .na
405 \fB\fBoff-line\fR\fR
406 .ad
407 .RS 12n
408 Set the CPU offline.
409 .RE
411 .sp
412 .ne 2
413 .na
414 \fB\fBon-line\fR\fR
415 .ad
416 .RS 12n
417 Set the CPU online.
418 .RE
420 .sp
421 .ne 2
422 .na
423 \fB\fBno-intr\fR\fR
424 .ad
425 .RS 12n
426 Disable interrupt processing on the CPU.
427 .RE
429 .sp
430 .LP
431 These values are defined in <\fBsys/processor.h\fR> as the \fBPS_OFFLINE\fR,
432 \fBPS_ONLINE\fR, and \fBPS_NOINTR\fR macros.
433 .SH INTERFACES
434 .sp
435 .LP
436 The shared object \fBlibpool.so.1\fR provides the public interfaces defined
437 below. See \fBIntro\fR(3) for additional information on shared object
438 interfaces.
439 .sp
441 .sp
442 .TS
443 l l
444 l l .
445 \fBpool_associate\fR \fBpool_component_info\fR
446 \fBpool_component_to_elem\fR \fBpool_conf_alloc\fR
447 \fBpool_conf_close\fR \fBpool_conf_commit\fR
448 \fBpool_conf_export\fR \fBpool_conf_free\fR
449 \fBpool_conf_info\fR \fBpool_conf_location\fR
450 \fBpool_conf_open\fR \fBpool_conf_remove\fR
451 \fBpool_conf_rollback\fR \fBpool_conf_status\fR
452 \fBpool_conf_to_elem\fR \fBpool_conf_update\fR
453 \fBpool_conf_validate\fR \fBpool_create\fR
454 \fBpool_destroy\fR \fBpool_dissociate\fR
455 \fBpool_dynamic_location\fR \fBpool_error\fR
456 \fBpool_get_binding\fR \fBpool_get_owning_resource\fR
457 \fBpool_get_pool\fR \fBpool_get_property\fR
458 \fBpool_get_resource\fR \fBpool_get_resource_binding\fR
459 \fBpool_get_status\fR \fBpool_info\fR
460 \fBpool_put_property\fR \fBpool_query_components\fR
461 \fBpool_query_pool_resources\fR \fBpool_query_pools\fR
462 \fBpool_query_resource_components\fR \fBpool_query_resources\fR
463 \fBpool_resource_create\fR \fBpool_resource_destroy\fR
464 \fBpool_resource_info\fR \fBpool_resource_to_elem\fR
465 \fBpool_resource_transfer\fR \fBpool_resource_type_list\fR
466 \fBpool_resource_xtransfer\fR \fBpool_rm_property\fR
467 \fBpool_set_binding\fR \fBpool_set_status\fR
468 \fBpool_static_location\fR \fBpool_strerror\fR
469 \fBpool_to_elem\fR \fBpool_value_alloc\fR
470 \fBpool_value_free\fR \fBpool_value_get_bool\fR
471 \fBpool_value_get_double\fR \fBpool_value_get_int64\fR
472 \fBpool_value_get_name\fR \fBpool_value_get_string\fR
473 \fBpool_value_get_type\fR \fBpool_value_get_uint64\fR
474 \fBpool_value_set_bool\fR \fBpool_value_set_double\fR
475 \fBpool_value_set_int64\fR \fBpool_value_set_name\fR
476 \fBpool_value_set_string\fR \fBpool_value_set_uint64\fR
477 \fBpool_version\fR \fBpool_walk_components\fR
478 \fBpool_walk_pools\fR \fBpool_walk_properties\fR
479 \fBpool_walk_resources\fR
480 .TE
482 .SH FILES
483 .sp
484 .ne 2
485 .na
486 \fB\fB/usr/lib/libpool.so.1\fR\fR
487 .ad
488 .RS 28n
489 shared object
490 .RE
492 .sp
493 .ne 2
494 .na
495 \fB\fB/usr/lib/64/libpool.so.1\fR\fR
496 .ad
497 .RS 28n
498 64-bit shared object
499 .RE
501 .SH ATTRIBUTES
502 .sp
503 .LP
504 See \fBattributes\fR(5) for descriptions of the following attributes:
505 .sp
507 .sp
508 .TS
509 box;
510 c | c
511 l | l .
512 ATTRIBUTE TYPE ATTRIBUTE VALUE
513 _
514 CSI Enabled
515 _
516 Interface Stability Unstable
517 _
518 MT-Level Safe
519 .TE
521 .SH SEE ALSO
522 .sp
523 .LP
524 \fBIntro\fR(3), \fBpool_component_info\fR(3POOL), \fBpool_conf_open\fR(3POOL),
525 \fBpool_conf_to_elem\fR(3POOL), \fBpool_create\fR(3POOL),
526 \fBpool_error\fR(3POOL), \fBpool_get_binding\fR(3POOL),
527 \fBpool_get_property\fR(3POOL), \fBpool_get_resource\fR(3POOL),
528 \fBpool_resource_create\fR(3POOL), \fBpool_value_alloc\fR(3POOL),
529 \fBpool_walk_pools\fR(3POOL), \fBattributes\fR(5), \fBsmf\fR(5)
530 .SH NOTES
531 .sp
532 .LP
533 Functions in \fBlibpool\fR can be used to manipulate static configurations even
534 when the pools facility is not enabled. See \fBpooladm\fR(1M) and
535 \fBpool_set_status\fR(3POOL) for more information about enabling the pools
536 facility. The pools facility must be enabled, however, to modify the dynamic
537 configuration.
538 .sp
539 .LP
540 Since the Resource Pools facility is an \fBsmf\fR(5) service, it can also be
541 enabled and disabled using the standard Service Management Facility (SMF)
542 interfaces.