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