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