]>
git.proxmox.com Git - mirror_zfs.git/blob - lib/libspl/include/sys/kstat.h
4 * The contents of this file are subject to the terms of the
5 * Common Development and Distribution License (the "License").
6 * You may not use this file except in compliance with the License.
8 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9 * or http://www.opensolaris.org/os/licensing.
10 * See the License for the specific language governing permissions
11 * and limitations under the License.
13 * When distributing Covered Code, include this CDDL HEADER in each
14 * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15 * If applicable, add the following below this CDDL HEADER, with the
16 * fields enclosed by brackets "[]" replaced with your own identifying
17 * information: Portions Copyright [yyyy] [name of copyright owner]
22 * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
23 * Use is subject to license terms.
32 * Definition of general kernel statistics structures and /dev/kstat ioctls
35 #include <sys/types.h>
42 typedef int kid_t
; /* unique kstat id */
45 * Kernel statistics driver (/dev/kstat) ioctls
48 #define KSTAT_IOC_BASE ('K' << 8)
50 #define KSTAT_IOC_CHAIN_ID KSTAT_IOC_BASE | 0x01
51 #define KSTAT_IOC_READ KSTAT_IOC_BASE | 0x02
52 #define KSTAT_IOC_WRITE KSTAT_IOC_BASE | 0x03
55 * /dev/kstat ioctl usage (kd denotes /dev/kstat descriptor):
57 * kcid = ioctl(kd, KSTAT_IOC_CHAIN_ID, NULL);
58 * kcid = ioctl(kd, KSTAT_IOC_READ, kstat_t *);
59 * kcid = ioctl(kd, KSTAT_IOC_WRITE, kstat_t *);
62 #define KSTAT_STRLEN 255 /* 254 chars + NULL; must be 16 * n - 1 */
65 * The generic kstat header
68 typedef struct kstat
{
70 * Fields relevant to both kernel and user
72 hrtime_t ks_crtime
; /* creation time (from gethrtime()) */
73 struct kstat
*ks_next
; /* kstat chain linkage */
74 kid_t ks_kid
; /* unique kstat ID */
75 char ks_module
[KSTAT_STRLEN
]; /* provider module name */
76 uchar_t ks_resv
; /* reserved, currently just padding */
77 int ks_instance
; /* provider module's instance */
78 char ks_name
[KSTAT_STRLEN
]; /* kstat name */
79 uchar_t ks_type
; /* kstat data type */
80 char ks_class
[KSTAT_STRLEN
]; /* kstat class */
81 uchar_t ks_flags
; /* kstat flags */
82 void *ks_data
; /* kstat type-specific data */
83 uint_t ks_ndata
; /* # of type-specific data records */
84 size_t ks_data_size
; /* total size of kstat data section */
85 hrtime_t ks_snaptime
; /* time of last data snapshot */
87 * Fields relevant to kernel only
89 int (*ks_update
)(struct kstat
*, int); /* dynamic update */
90 void *ks_private
; /* arbitrary provider-private data */
91 int (*ks_snapshot
)(struct kstat
*, void *, int);
92 void *ks_lock
; /* protects this kstat's data */
97 typedef int32_t kid32_t
;
99 typedef struct kstat32
{
101 * Fields relevant to both kernel and user
104 caddr32_t ks_next
; /* struct kstat pointer */
106 char ks_module
[KSTAT_STRLEN
];
109 char ks_name
[KSTAT_STRLEN
];
111 char ks_class
[KSTAT_STRLEN
];
113 caddr32_t ks_data
; /* type-specific data */
115 size32_t ks_data_size
;
116 hrtime_t ks_snaptime
;
118 * Fields relevant to kernel only (only needed here for padding)
121 caddr32_t _ks_private
;
122 int32_t _ks_snapshot
;
126 #endif /* _SYSCALL32 */
129 * kstat structure and locking strategy
131 * Each kstat consists of a header section (a kstat_t) and a data section.
132 * The system maintains a set of kstats, protected by kstat_chain_lock.
133 * kstat_chain_lock protects all additions to/deletions from this set,
134 * as well as all changes to kstat headers. kstat data sections are
135 * *optionally* protected by the per-kstat ks_lock. If ks_lock is non-NULL,
136 * kstat clients (e.g. /dev/kstat) will acquire this lock for all of their
137 * operations on that kstat. It is up to the kstat provider to decide whether
138 * guaranteeing consistent data to kstat clients is sufficiently important
139 * to justify the locking cost. Note, however, that most statistic updates
140 * already occur under one of the provider's mutexes, so if the provider sets
141 * ks_lock to point to that mutex, then kstat data locking is free.
143 * NOTE: variable-size kstats MUST employ kstat data locking, to prevent
144 * data-size races with kstat clients.
146 * NOTE: ks_lock is really of type (kmutex_t *); it is declared as (void *)
147 * in the kstat header so that users don't have to be exposed to all of the
148 * kernel's lock-related data structures.
153 #define KSTAT_ENTER(k) \
154 { kmutex_t *lp = (k)->ks_lock; if (lp) mutex_enter(lp); }
156 #define KSTAT_EXIT(k) \
157 { kmutex_t *lp = (k)->ks_lock; if (lp) mutex_exit(lp); }
159 #define KSTAT_UPDATE(k, rw) (*(k)->ks_update)((k), (rw))
161 #define KSTAT_SNAPSHOT(k, buf, rw) (*(k)->ks_snapshot)((k), (buf), (rw))
163 #endif /* defined(_KERNEL) */
168 * All times associated with kstats (e.g. creation time, snapshot time,
169 * kstat_timer_t and kstat_io_t timestamps, etc.) are 64-bit nanosecond values,
170 * as returned by gethrtime(). The accuracy of these timestamps is machine
171 * dependent, but the precision (units) is the same across all platforms.
175 * kstat identity (KID)
177 * Each kstat is assigned a unique KID (kstat ID) when it is added to the
178 * global kstat chain. The KID is used as a cookie by /dev/kstat to
179 * request information about the corresponding kstat. There is also
180 * an identity associated with the entire kstat chain, kstat_chain_id,
181 * which is bumped each time a kstat is added or deleted. /dev/kstat uses
182 * the chain ID to detect changes in the kstat chain (e.g., a new disk
183 * coming online) between ioctl()s.
187 * kstat module, kstat instance
189 * ks_module and ks_instance contain the name and instance of the module
190 * that created the kstat. In cases where there can only be one instance,
191 * ks_instance is 0. The kernel proper (/kernel/unix) uses "unix" as its
198 * ks_name gives a meaningful name to a kstat. The full kstat namespace
199 * is module.instance.name, so the name only need be unique within a
200 * module. kstat_create() will fail if you try to create a kstat with
201 * an already-used (ks_module, ks_instance, ks_name) triplet. Spaces are
202 * allowed in kstat names, but strongly discouraged, since they hinder
203 * awk-style processing at user level.
209 * The kstat mechanism provides several flavors of kstat data, defined
210 * below. The "raw" kstat type is just treated as an array of bytes; you
211 * can use this to export any kind of data you want.
213 * Some kstat types allow multiple data structures per kstat, e.g.
214 * KSTAT_TYPE_NAMED; others do not. This is part of the spec for each
217 * User-level tools should *not* rely on the #define KSTAT_NUM_TYPES. To
218 * get this information, read out the standard system kstat "kstat_types".
221 #define KSTAT_TYPE_RAW 0 /* can be anything */
223 #define KSTAT_TYPE_NAMED 1 /* name/value pair */
225 #define KSTAT_TYPE_INTR 2 /* interrupt statistics */
227 #define KSTAT_TYPE_IO 3 /* I/O statistics */
229 #define KSTAT_TYPE_TIMER 4 /* event timer */
232 #define KSTAT_NUM_TYPES 5
237 * Each kstat can be characterized as belonging to some broad class
238 * of statistics, e.g. disk, tape, net, vm, streams, etc. This field
239 * can be used as a filter to extract related kstats. The following
240 * values are currently in use: disk, tape, net, controller, vm, kvm,
241 * hat, streams, kstat, and misc. (The kstat class encompasses things
248 * Any of the following flags may be passed to kstat_create(). They are
249 * all zero by default.
251 * KSTAT_FLAG_VIRTUAL:
253 * Tells kstat_create() not to allocate memory for the
254 * kstat data section; instead, you will set the ks_data
255 * field to point to the data you wish to export. This
256 * provides a convenient way to export existing data
259 * KSTAT_FLAG_VAR_SIZE:
261 * The size of the kstat you are creating will vary over time.
262 * For example, you may want to use the kstat mechanism to
263 * export a linked list. NOTE: The kstat framework does not
264 * manage the data section, so all variable-size kstats must be
265 * virtual kstats. Moreover, variable-size kstats MUST employ
266 * kstat data locking to prevent data-size races with kstat
267 * clients. See the section on "kstat snapshot" for details.
269 * KSTAT_FLAG_WRITABLE:
271 * Makes the kstat's data section writable by root.
272 * The ks_snapshot routine (see below) does not need to check for
273 * this; permission checking is handled in the kstat driver.
275 * KSTAT_FLAG_PERSISTENT:
277 * Indicates that this kstat is to be persistent over time.
278 * For persistent kstats, kstat_delete() simply marks the
279 * kstat as dormant; a subsequent kstat_create() reactivates
280 * the kstat. This feature is provided so that statistics
281 * are not lost across driver close/open (e.g., raw disk I/O
282 * on a disk with no mounted partitions.)
283 * NOTE: Persistent kstats cannot be virtual, since ks_data
284 * points to garbage as soon as the driver goes away.
286 * The following flags are maintained by the kstat framework:
288 * KSTAT_FLAG_DORMANT:
290 * For persistent kstats, indicates that the kstat is in the
291 * dormant state (e.g., the corresponding device is closed).
293 * KSTAT_FLAG_INVALID:
295 * This flag is set when a kstat is in a transitional state,
296 * e.g. between kstat_create() and kstat_install().
297 * kstat clients must not attempt to access the kstat's data
298 * if this flag is set.
301 #define KSTAT_FLAG_VIRTUAL 0x01
302 #define KSTAT_FLAG_VAR_SIZE 0x02
303 #define KSTAT_FLAG_WRITABLE 0x04
304 #define KSTAT_FLAG_PERSISTENT 0x08
305 #define KSTAT_FLAG_DORMANT 0x10
306 #define KSTAT_FLAG_INVALID 0x20
307 #define KSTAT_FLAG_LONGSTRINGS 0x40
308 #define KSTAT_FLAG_NO_HEADERS 0x80
311 * Dynamic update support
313 * The kstat mechanism allows for an optional ks_update function to update
314 * kstat data. This is useful for drivers where the underlying device
315 * keeps cheap hardware stats, but extraction is expensive. Instead of
316 * constantly keeping the kstat data section up to date, you can supply a
317 * ks_update function which updates the kstat's data section on demand.
318 * To take advantage of this feature, simply set the ks_update field before
319 * calling kstat_install().
321 * The ks_update function, if supplied, must have the following structure:
324 * foo_kstat_update(kstat_t *ksp, int rw)
326 * if (rw == KSTAT_WRITE) {
327 * ... update the native stats from ksp->ks_data;
328 * return EACCES if you don't support this
330 * ... update ksp->ks_data from the native stats
334 * The ks_update return codes are: 0 for success, EACCES if you don't allow
335 * KSTAT_WRITE, and EIO for any other type of error.
337 * In general, the ks_update function may need to refer to provider-private
338 * data; for example, it may need a pointer to the provider's raw statistics.
339 * The ks_private field is available for this purpose. Its use is entirely
340 * at the provider's discretion.
342 * All variable-size kstats MUST supply a ks_update routine, which computes
343 * and sets ks_data_size (and ks_ndata if that is meaningful), since these
344 * are needed to perform kstat snapshots (see below).
346 * No kstat locking should be done inside the ks_update routine. The caller
347 * will already be holding the kstat's ks_lock (to ensure consistent data).
351 #define KSTAT_WRITE 1
356 * In order to get a consistent view of a kstat's data, clients must obey
357 * the kstat's locking strategy. However, these clients may need to perform
358 * operations on the data which could cause a fault (e.g. copyout()), or
359 * operations which are simply expensive. Doing so could cause deadlock
360 * (e.g. if you're holding a disk's kstat lock which is ultimately required
361 * to resolve a copyout() fault), performance degradation (since the providers'
362 * activity is serialized at the kstat lock), device timing problems, etc.
364 * To avoid these problems, kstat data is provided via snapshots. Taking
365 * a snapshot is a simple process: allocate a wired-down kernel buffer,
366 * acquire the kstat's data lock, copy the data into the buffer ("take the
367 * snapshot"), and release the lock. This ensures that the kstat's data lock
368 * will be held as briefly as possible, and that no faults will occur while
371 * Normally, the snapshot is taken by default_kstat_snapshot(), which
372 * timestamps the data (sets ks_snaptime), copies it, and does a little
373 * massaging to deal with incomplete transactions on i/o kstats. However,
374 * this routine only works for kstats with contiguous data (the typical case).
375 * If you create a kstat whose data is, say, a linked list, you must provide
376 * your own ks_snapshot routine. The routine you supply must have the
377 * following prototype (replace "foo" with something appropriate):
379 * int foo_kstat_snapshot(kstat_t *ksp, void *buf, int rw);
381 * The minimal snapshot routine -- one which copies contiguous data that
382 * doesn't need any massaging -- would be this:
384 * ksp->ks_snaptime = gethrtime();
385 * if (rw == KSTAT_WRITE)
386 * memcpy(ksp->ks_data, buf, ksp->ks_data_size);
388 * memcpy(buf, ksp->ks_data, ksp->ks_data_size);
391 * A more illuminating example is taking a snapshot of a linked list:
393 * ksp->ks_snaptime = gethrtime();
394 * if (rw == KSTAT_WRITE)
395 * return (EACCES); ... See below ...
396 * for (foo = first_foo; foo; foo = foo->next) {
397 * memcpy(buf, foo, sizeof (struct foo));
398 * buf = ((struct foo *) buf) + 1;
402 * In the example above, we have decided that we don't want to allow
403 * KSTAT_WRITE access, so we return EACCES if this is attempted.
405 * The key points are:
407 * (1) ks_snaptime must be set (via gethrtime()) to timestamp the data.
408 * (2) Data gets copied from the kstat to the buffer on KSTAT_READ,
409 * and from the buffer to the kstat on KSTAT_WRITE.
410 * (3) ks_snapshot return values are: 0 for success, EACCES if you
411 * don't allow KSTAT_WRITE, and EIO for any other type of error.
413 * Named kstats (see section on "Named statistics" below) containing long
414 * strings (KSTAT_DATA_STRING) need special handling. The kstat driver
415 * assumes that all strings are copied into the buffer after the array of
416 * named kstats, and the pointers (KSTAT_NAMED_STR_PTR()) are updated to point
417 * into the copy within the buffer. The default snapshot routine does this,
418 * but overriding routines should contain at least the following:
420 * if (rw == KSTAT_READ) {
421 * kstat_named_t *knp = buf;
422 * char *end = knp + ksp->ks_ndata;
425 * ... Do the regular copy ...
426 * memcpy(buf, ksp->ks_data, sizeof (kstat_named_t) * ksp->ks_ndata);
428 * for (i = 0; i < ksp->ks_ndata; i++, knp++) {
429 * if (knp[i].data_type == KSTAT_DATA_STRING &&
430 * KSTAT_NAMED_STR_PTR(knp) != NULL) {
431 * memcpy(end, KSTAT_NAMED_STR_PTR(knp),
432 * KSTAT_NAMED_STR_BUFLEN(knp));
433 * KSTAT_NAMED_STR_PTR(knp) = end;
434 * end += KSTAT_NAMED_STR_BUFLEN(knp);
442 * List of arbitrary name=value statistics.
445 typedef struct kstat_named
{
446 char name
[KSTAT_STRLEN
]; /* name of counter */
447 uchar_t data_type
; /* data type */
449 char c
[16]; /* enough for 128-bit ints */
454 char *ptr
; /* NULL-term string */
455 #if defined(_KERNEL) && defined(_MULTI_DATAMODEL)
458 char __pad
[8]; /* 64-bit padding */
460 uint32_t len
; /* # bytes for strlen + '\0' */
463 * The int64_t and uint64_t types are not valid for a maximally conformant
464 * 32-bit compilation environment (cc -Xc) using compilers prior to the
465 * introduction of C99 conforming compiler (reference ISO/IEC 9899:1990).
466 * In these cases, the visibility of i64 and ui64 is only permitted for
467 * 64-bit compilation environments or 32-bit non-maximally conformant
468 * C89 or C90 ANSI C compilation environments (cc -Xt and cc -Xa). In the
469 * C99 ANSI C compilation environment, the long long type is supported.
470 * The _INT64_TYPE is defined by the implementation (see sys/int_types.h).
472 #if defined(_INT64_TYPE)
479 /* These structure members are obsolete */
485 } value
; /* value of counter */
488 #define KSTAT_DATA_CHAR 0
489 #define KSTAT_DATA_INT32 1
490 #define KSTAT_DATA_UINT32 2
491 #define KSTAT_DATA_INT64 3
492 #define KSTAT_DATA_UINT64 4
495 #define KSTAT_DATA_LONG KSTAT_DATA_INT32
496 #define KSTAT_DATA_ULONG KSTAT_DATA_UINT32
498 #if !defined(_KERNEL)
499 #define KSTAT_DATA_LONG KSTAT_DATA_INT64
500 #define KSTAT_DATA_ULONG KSTAT_DATA_UINT64
502 #define KSTAT_DATA_LONG 7 /* only visible to the kernel */
503 #define KSTAT_DATA_ULONG 8 /* only visible to the kernel */
504 #endif /* !_KERNEL */
508 * Statistics exporting named kstats with long strings (KSTAT_DATA_STRING)
509 * may not make the assumption that ks_data_size is equal to (ks_ndata * sizeof
510 * (kstat_named_t)). ks_data_size in these cases is equal to the sum of the
511 * amount of space required to store the strings (ie, the sum of
512 * KSTAT_NAMED_STR_BUFLEN() for all KSTAT_DATA_STRING statistics) plus the
513 * space required to store the kstat_named_t's.
515 * The default update routine will update ks_data_size automatically for
516 * variable-length kstats containing long strings (using the default update
517 * routine only makes sense if the string is the only thing that is changing
518 * in size, and ks_ndata is constant). Fixed-length kstats containing long
519 * strings must explicitly change ks_data_size (after creation but before
520 * initialization) to reflect the correct amount of space required for the
521 * long strings and the kstat_named_t's.
523 #define KSTAT_DATA_STRING 9
525 /* These types are obsolete */
527 #define KSTAT_DATA_LONGLONG KSTAT_DATA_INT64
528 #define KSTAT_DATA_ULONGLONG KSTAT_DATA_UINT64
529 #define KSTAT_DATA_FLOAT 5
530 #define KSTAT_DATA_DOUBLE 6
532 #define KSTAT_NAMED_PTR(kptr) ((kstat_named_t *)(kptr)->ks_data)
535 * Retrieve the pointer of the string contained in the given named kstat.
537 #define KSTAT_NAMED_STR_PTR(knptr) ((knptr)->value.str.addr.ptr)
540 * Retrieve the length of the buffer required to store the string in the given
543 #define KSTAT_NAMED_STR_BUFLEN(knptr) ((knptr)->value.str.len)
546 * Interrupt statistics.
548 * An interrupt is a hard interrupt (sourced from the hardware device
549 * itself), a soft interrupt (induced by the system via the use of
550 * some system interrupt source), a watchdog interrupt (induced by
551 * a periodic timer call), spurious (an interrupt entry point was
552 * entered but there was no interrupt condition to service),
553 * or multiple service (an interrupt condition was detected and
554 * serviced just prior to returning from any of the other types).
556 * Measurement of the spurious class of interrupts is useful for
557 * autovectored devices in order to pinpoint any interrupt latency
558 * problems in a particular system configuration.
560 * Devices that have more than one interrupt of the same
561 * type should use multiple structures.
564 #define KSTAT_INTR_HARD 0
565 #define KSTAT_INTR_SOFT 1
566 #define KSTAT_INTR_WATCHDOG 2
567 #define KSTAT_INTR_SPURIOUS 3
568 #define KSTAT_INTR_MULTSVC 4
570 #define KSTAT_NUM_INTRS 5
572 typedef struct kstat_intr
{
573 uint_t intrs
[KSTAT_NUM_INTRS
]; /* interrupt counters */
576 #define KSTAT_INTR_PTR(kptr) ((kstat_intr_t *)(kptr)->ks_data)
582 typedef struct kstat_io
{
587 * The counters should be updated at the end of service
588 * (e.g., just prior to calling biodone()).
591 u_longlong_t nread
; /* number of bytes read */
592 u_longlong_t nwritten
; /* number of bytes written */
593 uint_t reads
; /* number of read operations */
594 uint_t writes
; /* number of write operations */
597 * Accumulated time and queue length statistics.
599 * Accumulated time statistics are kept as a running sum
600 * of "active" time. Queue length statistics are kept as a
601 * running sum of the product of queue length and elapsed time
602 * at that length -- i.e., a Riemann sum for queue length
603 * integrated against time. (You can also think of the active time
604 * as a Riemann sum, for the boolean function (queue_length > 0)
605 * integrated against time, or you can think of it as the
606 * Lebesgue measure of the set on which queue_length > 0.)
613 * Length | _________ | |
618 * |_______________________________|
621 * At each change of state (entry or exit from the queue),
622 * we add the elapsed time (since the previous state change)
623 * to the active time if the queue length was non-zero during
624 * that interval; and we add the product of the elapsed time
625 * times the queue length to the running length*time sum.
627 * This method is generalizable to measuring residency
628 * in any defined system: instead of queue lengths, think
629 * of "outstanding RPC calls to server X".
631 * A large number of I/O subsystems have at least two basic
632 * "lists" of transactions they manage: one for transactions
633 * that have been accepted for processing but for which processing
634 * has yet to begin, and one for transactions which are actively
635 * being processed (but not done). For this reason, two cumulative
636 * time statistics are defined here: wait (pre-service) time,
637 * and run (service) time.
639 * All times are 64-bit nanoseconds (hrtime_t), as returned by
642 * The units of cumulative busy time are accumulated nanoseconds.
643 * The units of cumulative length*time products are elapsed time
644 * times queue length.
646 * Updates to the fields below are performed implicitly by calls to
647 * these five functions:
649 * kstat_waitq_enter()
654 * kstat_waitq_to_runq() (see below)
655 * kstat_runq_back_to_waitq() (see below)
657 * Since kstat_waitq_exit() is typically followed immediately
658 * by kstat_runq_enter(), there is a single kstat_waitq_to_runq()
659 * function which performs both operations. This is a performance
660 * win since only one timestamp is required.
662 * In some instances, it may be necessary to move a request from
663 * the run queue back to the wait queue, e.g. for write throttling.
664 * For these situations, call kstat_runq_back_to_waitq().
666 * These fields should never be updated by any other means.
669 hrtime_t wtime
; /* cumulative wait (pre-service) time */
670 hrtime_t wlentime
; /* cumulative wait length*time product */
671 hrtime_t wlastupdate
; /* last time wait queue changed */
672 hrtime_t rtime
; /* cumulative run (service) time */
673 hrtime_t rlentime
; /* cumulative run length*time product */
674 hrtime_t rlastupdate
; /* last time run queue changed */
676 uint_t wcnt
; /* count of elements in wait state */
677 uint_t rcnt
; /* count of elements in run state */
681 #define KSTAT_IO_PTR(kptr) ((kstat_io_t *)(kptr)->ks_data)
684 * Event timer statistics - cumulative elapsed time and number of events.
686 * Updates to these fields are performed implicitly by calls to
687 * kstat_timer_start() and kstat_timer_stop().
690 typedef struct kstat_timer
{
691 char name
[KSTAT_STRLEN
]; /* event name */
692 uchar_t resv
; /* reserved */
693 u_longlong_t num_events
; /* number of events */
694 hrtime_t elapsed_time
; /* cumulative elapsed time */
695 hrtime_t min_time
; /* shortest event duration */
696 hrtime_t max_time
; /* longest event duration */
697 hrtime_t start_time
; /* previous event start time */
698 hrtime_t stop_time
; /* previous event stop time */
701 #define KSTAT_TIMER_PTR(kptr) ((kstat_timer_t *)(kptr)->ks_data)
705 #include <sys/t_lock.h>
707 extern kid_t kstat_chain_id
; /* bumped at each state change */
708 extern void kstat_init(void); /* initialize kstat framework */
711 * Adding and deleting kstats.
713 * The typical sequence to add a kstat is:
715 * ksp = kstat_create(module, instance, name, class, type, ndata, flags);
717 * ... provider initialization, if necessary
718 * kstat_install(ksp);
721 * There are three logically distinct steps here:
723 * Step 1: System Initialization (kstat_create)
725 * kstat_create() performs system initialization. kstat_create()
726 * allocates memory for the entire kstat (header plus data), initializes
727 * all header fields, initializes the data section to all zeroes, assigns
728 * a unique KID, and puts the kstat onto the system's kstat chain.
729 * The returned kstat is marked invalid (KSTAT_FLAG_INVALID is set),
730 * because the provider (caller) has not yet had a chance to initialize
733 * By default, kstats are exported to all zones on the system. A kstat may be
734 * created via kstat_create_zone() to specify a zone to which the statistics
735 * should be exported. kstat_zone_add() may be used to specify additional
736 * zones to which the statistics are to be exported.
738 * Step 2: Provider Initialization
740 * The provider performs any necessary initialization of the data section,
741 * e.g. setting the name fields in a KSTAT_TYPE_NAMED. Virtual kstats set
742 * the ks_data field at this time. The provider may also set the ks_update,
743 * ks_snapshot, ks_private, and ks_lock fields if necessary.
745 * Step 3: Installation (kstat_install)
747 * Once the kstat is completely initialized, kstat_install() clears the
748 * INVALID flag, thus making the kstat accessible to the outside world.
749 * kstat_install() also clears the DORMANT flag for persistent kstats.
751 * Removing a kstat from the system
753 * kstat_delete(ksp) removes ksp from the kstat chain and frees all
754 * associated system resources. NOTE: When you call kstat_delete(),
755 * you must NOT be holding that kstat's ks_lock. Otherwise, you may
756 * deadlock with a kstat reader.
760 * From the provider's point of view, persistence is transparent. The only
761 * difference between ephemeral (normal) kstats and persistent kstats
762 * is that you pass KSTAT_FLAG_PERSISTENT to kstat_create(). Magically,
763 * this has the effect of making your data visible even when you're
764 * not home. Persistence is important to tools like iostat, which want
765 * to get a meaningful picture of disk activity. Without persistence,
766 * raw disk i/o statistics could never accumulate: they would come and
767 * go with each open/close of the raw device.
769 * The magic of persistence works by slightly altering the behavior of
770 * kstat_create() and kstat_delete(). The first call to kstat_create()
771 * creates a new kstat, as usual. However, kstat_delete() does not
772 * actually delete the kstat: it performs one final update of the data
773 * (i.e., calls the ks_update routine), marks the kstat as dormant, and
774 * sets the ks_lock, ks_update, ks_private, and ks_snapshot fields back
775 * to their default values (since they might otherwise point to garbage,
776 * e.g. if the provider is going away). kstat clients can still access
777 * the dormant kstat just like a live kstat; they just continue to see
778 * the final data values as long as the kstat remains dormant.
779 * All subsequent kstat_create() calls simply find the already-existing,
780 * dormant kstat and return a pointer to it, without altering any fields.
781 * The provider then performs its usual initialization sequence, and
782 * calls kstat_install(). kstat_install() uses the old data values to
783 * initialize the native data (i.e., ks_update is called with KSTAT_WRITE),
784 * thus making it seem like you were never gone.
787 extern kstat_t
*kstat_create(const char *, int, const char *, const char *,
788 uchar_t
, uint_t
, uchar_t
);
789 extern kstat_t
*kstat_create_zone(const char *, int, const char *,
790 const char *, uchar_t
, uint_t
, uchar_t
, zoneid_t
);
791 extern void kstat_install(kstat_t
*);
792 extern void kstat_delete(kstat_t
*);
793 extern void kstat_named_setstr(kstat_named_t
*knp
, const char *src
);
794 extern void kstat_set_string(char *, const char *);
795 extern void kstat_delete_byname(const char *, int, const char *);
796 extern void kstat_delete_byname_zone(const char *, int, const char *, zoneid_t
);
797 extern void kstat_named_init(kstat_named_t
*, const char *, uchar_t
);
798 extern void kstat_timer_init(kstat_timer_t
*, const char *);
799 extern void kstat_timer_start(kstat_timer_t
*);
800 extern void kstat_timer_stop(kstat_timer_t
*);
802 extern void kstat_zone_add(kstat_t
*, zoneid_t
);
803 extern void kstat_zone_remove(kstat_t
*, zoneid_t
);
804 extern int kstat_zone_find(kstat_t
*, zoneid_t
);
806 extern kstat_t
*kstat_hold_bykid(kid_t kid
, zoneid_t
);
807 extern kstat_t
*kstat_hold_byname(const char *, int, const char *, zoneid_t
);
808 extern void kstat_rele(kstat_t
*);
810 #endif /* defined(_KERNEL) */
816 #endif /* _SYS_KSTAT_H */