1 /* 2 * CDDL HEADER START 3 * 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. 7 * 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. 12 * 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] 18 * 19 * CDDL HEADER END 20 */ 21 /* 22 * Copyright 2006 Sun Microsystems, Inc. All rights reserved. 23 * Use is subject to license terms. 24 */ 25 26 #ifndef _SYS_KSTAT_H 27 #define _SYS_KSTAT_H 28 29 30 31 /* 32 * Definition of general kernel statistics structures and /dev/kstat ioctls 33 */ 34 35 #include <sys/types.h> 36 #include <sys/time.h> 37 38 #ifdef __cplusplus 39 extern "C" { 40 #endif 41 42 typedef int kid_t; /* unique kstat id */ 43 44 /* 45 * Kernel statistics driver (/dev/kstat) ioctls 46 */ 47 48 #define KSTAT_IOC_BASE ('K' << 8) 49 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 53 54 /* 55 * /dev/kstat ioctl usage (kd denotes /dev/kstat descriptor): 56 * 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 *); 60 */ 61 62 #define KSTAT_STRLEN 255 /* 254 chars + NULL; must be 16 * n - 1 */ 63 64 /* 65 * The generic kstat header 66 */ 67 68 typedef struct kstat { 69 /* 70 * Fields relevant to both kernel and user 71 */ 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 */ 86 /* 87 * Fields relevant to kernel only 88 */ 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 */ 93 } kstat_t; 94 95 #ifdef _SYSCALL32 96 97 typedef int32_t kid32_t; 98 99 typedef struct kstat32 { 100 /* 101 * Fields relevant to both kernel and user 102 */ 103 hrtime_t ks_crtime; 104 caddr32_t ks_next; /* struct kstat pointer */ 105 kid32_t ks_kid; 106 char ks_module[KSTAT_STRLEN]; 107 uint8_t ks_resv; 108 int32_t ks_instance; 109 char ks_name[KSTAT_STRLEN]; 110 uint8_t ks_type; 111 char ks_class[KSTAT_STRLEN]; 112 uint8_t ks_flags; 113 caddr32_t ks_data; /* type-specific data */ 114 uint32_t ks_ndata; 115 size32_t ks_data_size; 116 hrtime_t ks_snaptime; 117 /* 118 * Fields relevant to kernel only (only needed here for padding) 119 */ 120 int32_t _ks_update; 121 caddr32_t _ks_private; 122 int32_t _ks_snapshot; 123 caddr32_t _ks_lock; 124 } kstat32_t; 125 126 #endif /* _SYSCALL32 */ 127 128 /* 129 * kstat structure and locking strategy 130 * 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. 142 * 143 * NOTE: variable-size kstats MUST employ kstat data locking, to prevent 144 * data-size races with kstat clients. 145 * 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. 149 */ 150 151 #if defined(_KERNEL) 152 153 #define KSTAT_ENTER(k) \ 154 { kmutex_t *lp = (k)->ks_lock; if (lp) mutex_enter(lp); } 155 156 #define KSTAT_EXIT(k) \ 157 { kmutex_t *lp = (k)->ks_lock; if (lp) mutex_exit(lp); } 158 159 #define KSTAT_UPDATE(k, rw) (*(k)->ks_update)((k), (rw)) 160 161 #define KSTAT_SNAPSHOT(k, buf, rw) (*(k)->ks_snapshot)((k), (buf), (rw)) 162 163 #endif /* defined(_KERNEL) */ 164 165 /* 166 * kstat time 167 * 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. 172 */ 173 174 /* 175 * kstat identity (KID) 176 * 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. 184 */ 185 186 /* 187 * kstat module, kstat instance 188 * 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 192 * module name. 193 */ 194 195 /* 196 * kstat name 197 * 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. 204 */ 205 206 /* 207 * kstat type 208 * 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. 212 * 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 215 * kstat data type. 216 * 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". 219 */ 220 221 #define KSTAT_TYPE_RAW 0 /* can be anything */ 222 /* ks_ndata >= 1 */ 223 #define KSTAT_TYPE_NAMED 1 /* name/value pair */ 224 /* ks_ndata >= 1 */ 225 #define KSTAT_TYPE_INTR 2 /* interrupt statistics */ 226 /* ks_ndata == 1 */ 227 #define KSTAT_TYPE_IO 3 /* I/O statistics */ 228 /* ks_ndata == 1 */ 229 #define KSTAT_TYPE_TIMER 4 /* event timer */ 230 /* ks_ndata >= 1 */ 231 232 #define KSTAT_NUM_TYPES 5 233 234 /* 235 * kstat class 236 * 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 242 * like kstat_types.) 243 */ 244 245 /* 246 * kstat flags 247 * 248 * Any of the following flags may be passed to kstat_create(). They are 249 * all zero by default. 250 * 251 * KSTAT_FLAG_VIRTUAL: 252 * 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 257 * structures. 258 * 259 * KSTAT_FLAG_VAR_SIZE: 260 * 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. 268 * 269 * KSTAT_FLAG_WRITABLE: 270 * 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. 274 * 275 * KSTAT_FLAG_PERSISTENT: 276 * 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. 285 * 286 * The following flags are maintained by the kstat framework: 287 * 288 * KSTAT_FLAG_DORMANT: 289 * 290 * For persistent kstats, indicates that the kstat is in the 291 * dormant state (e.g., the corresponding device is closed). 292 * 293 * KSTAT_FLAG_INVALID: 294 * 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. 299 */ 300 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 309 310 /* 311 * Dynamic update support 312 * 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(). 320 * 321 * The ks_update function, if supplied, must have the following structure: 322 * 323 * int 324 * foo_kstat_update(kstat_t *ksp, int rw) 325 * { 326 * if (rw == KSTAT_WRITE) { 327 * ... update the native stats from ksp->ks_data; 328 * return EACCES if you don't support this 329 * } else { 330 * ... update ksp->ks_data from the native stats 331 * } 332 * } 333 * 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. 336 * 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. 341 * 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). 345 * 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). 348 */ 349 350 #define KSTAT_READ 0 351 #define KSTAT_WRITE 1 352 353 /* 354 * Kstat snapshot 355 * 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. 363 * 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 369 * the lock is held. 370 * 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): 378 * 379 * int foo_kstat_snapshot(kstat_t *ksp, void *buf, int rw); 380 * 381 * The minimal snapshot routine -- one which copies contiguous data that 382 * doesn't need any massaging -- would be this: 383 * 384 * ksp->ks_snaptime = gethrtime(); 385 * if (rw == KSTAT_WRITE) 386 * memcpy(ksp->ks_data, buf, ksp->ks_data_size); 387 * else 388 * memcpy(buf, ksp->ks_data, ksp->ks_data_size); 389 * return (0); 390 * 391 * A more illuminating example is taking a snapshot of a linked list: 392 * 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; 399 * } 400 * return (0); 401 * 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. 404 * 405 * The key points are: 406 * 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. 412 * 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: 419 * 420 * if (rw == KSTAT_READ) { 421 * kstat_named_t *knp = buf; 422 * char *end = knp + ksp->ks_ndata; 423 * uint_t i; 424 * 425 * ... Do the regular copy ... 426 * memcpy(buf, ksp->ks_data, sizeof (kstat_named_t) * ksp->ks_ndata); 427 * 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); 435 * } 436 * } 437 */ 438 439 /* 440 * Named statistics. 441 * 442 * List of arbitrary name=value statistics. 443 */ 444 445 typedef struct kstat_named { 446 char name[KSTAT_STRLEN]; /* name of counter */ 447 uchar_t data_type; /* data type */ 448 union { 449 char c[16]; /* enough for 128-bit ints */ 450 int32_t i32; 451 uint32_t ui32; 452 struct { 453 union { 454 char *ptr; /* NULL-term string */ 455 #if defined(_KERNEL) && defined(_MULTI_DATAMODEL) 456 caddr32_t ptr32; 457 #endif 458 char __pad[8]; /* 64-bit padding */ 459 } addr; 460 uint32_t len; /* # bytes for strlen + '\0' */ 461 } str; 462 /* 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). 471 */ 472 #if defined(_INT64_TYPE) 473 int64_t i64; 474 uint64_t ui64; 475 #endif 476 long l; 477 ulong_t ul; 478 479 /* These structure members are obsolete */ 480 481 longlong_t ll; 482 u_longlong_t ull; 483 float f; 484 double d; 485 } value; /* value of counter */ 486 } kstat_named_t; 487 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 493 494 #if !defined(_LP64) 495 #define KSTAT_DATA_LONG KSTAT_DATA_INT32 496 #define KSTAT_DATA_ULONG KSTAT_DATA_UINT32 497 #else 498 #if !defined(_KERNEL) 499 #define KSTAT_DATA_LONG KSTAT_DATA_INT64 500 #define KSTAT_DATA_ULONG KSTAT_DATA_UINT64 501 #else 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 */ 505 #endif /* !_LP64 */ 506 507 /* 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. 514 * 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. 522 */ 523 #define KSTAT_DATA_STRING 9 524 525 /* These types are obsolete */ 526 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 531 532 #define KSTAT_NAMED_PTR(kptr) ((kstat_named_t *)(kptr)->ks_data) 533 534 /* 535 * Retrieve the pointer of the string contained in the given named kstat. 536 */ 537 #define KSTAT_NAMED_STR_PTR(knptr) ((knptr)->value.str.addr.ptr) 538 539 /* 540 * Retrieve the length of the buffer required to store the string in the given 541 * named kstat. 542 */ 543 #define KSTAT_NAMED_STR_BUFLEN(knptr) ((knptr)->value.str.len) 544 545 /* 546 * Interrupt statistics. 547 * 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). 555 * 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. 559 * 560 * Devices that have more than one interrupt of the same 561 * type should use multiple structures. 562 */ 563 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 569 570 #define KSTAT_NUM_INTRS 5 571 572 typedef struct kstat_intr { 573 uint_t intrs[KSTAT_NUM_INTRS]; /* interrupt counters */ 574 } kstat_intr_t; 575 576 #define KSTAT_INTR_PTR(kptr) ((kstat_intr_t *)(kptr)->ks_data) 577 578 /* 579 * I/O statistics. 580 */ 581 582 typedef struct kstat_io { 583 584 /* 585 * Basic counters. 586 * 587 * The counters should be updated at the end of service 588 * (e.g., just prior to calling biodone()). 589 */ 590 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 */ 595 596 /* 597 * Accumulated time and queue length statistics. 598 * 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.) 607 * 608 * ^ 609 * | _________ 610 * 8 | i4 | 611 * | | | 612 * Queue 6 | | 613 * Length | _________ | | 614 * 4 | i2 |_______| | 615 * | | i3 | 616 * 2_______| | 617 * | i1 | 618 * |_______________________________| 619 * Time-> t1 t2 t3 t4 620 * 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. 626 * 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". 630 * 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. 638 * 639 * All times are 64-bit nanoseconds (hrtime_t), as returned by 640 * gethrtime(). 641 * 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. 645 * 646 * Updates to the fields below are performed implicitly by calls to 647 * these five functions: 648 * 649 * kstat_waitq_enter() 650 * kstat_waitq_exit() 651 * kstat_runq_enter() 652 * kstat_runq_exit() 653 * 654 * kstat_waitq_to_runq() (see below) 655 * kstat_runq_back_to_waitq() (see below) 656 * 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. 661 * 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(). 665 * 666 * These fields should never be updated by any other means. 667 */ 668 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 */ 675 676 uint_t wcnt; /* count of elements in wait state */ 677 uint_t rcnt; /* count of elements in run state */ 678 679 } kstat_io_t; 680 681 #define KSTAT_IO_PTR(kptr) ((kstat_io_t *)(kptr)->ks_data) 682 683 /* 684 * Event timer statistics - cumulative elapsed time and number of events. 685 * 686 * Updates to these fields are performed implicitly by calls to 687 * kstat_timer_start() and kstat_timer_stop(). 688 */ 689 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 */ 699 } kstat_timer_t; 700 701 #define KSTAT_TIMER_PTR(kptr) ((kstat_timer_t *)(kptr)->ks_data) 702 703 #if defined(_KERNEL) 704 705 #include <sys/t_lock.h> 706 707 extern kid_t kstat_chain_id; /* bumped at each state change */ 708 extern void kstat_init(void); /* initialize kstat framework */ 709 710 /* 711 * Adding and deleting kstats. 712 * 713 * The typical sequence to add a kstat is: 714 * 715 * ksp = kstat_create(module, instance, name, class, type, ndata, flags); 716 * if (ksp) { 717 * ... provider initialization, if necessary 718 * kstat_install(ksp); 719 * } 720 * 721 * There are three logically distinct steps here: 722 * 723 * Step 1: System Initialization (kstat_create) 724 * 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 731 * the data section. 732 * 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. 737 * 738 * Step 2: Provider Initialization 739 * 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. 744 * 745 * Step 3: Installation (kstat_install) 746 * 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. 750 * 751 * Removing a kstat from the system 752 * 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. 757 * 758 * Persistent kstats 759 * 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. 768 * 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. 785 */ 786 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 *); 801 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); 805 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 *); 809 810 #endif /* defined(_KERNEL) */ 811 812 #ifdef __cplusplus 813 } 814 #endif 815 816 #endif /* _SYS_KSTAT_H */ 817