1 '\" te
2 .\" Copyright 1999 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 TNF_KERNEL_PROBES 4 "Nov 8, 1999"
7 .SH NAME
8 tnf_kernel_probes \- TNF kernel probes
9 .SH DESCRIPTION
10 .sp
11 .LP
12 The set of probes (trace instrumentation points) available in the standard
13 kernel. The probes log trace data to a kernel trace buffer in Trace Normal
14 Form (TNF). Kernel probes are controlled by \fBprex\fR(1). A snapshot of the
15 kernel trace buffer can be made using \fBtnfxtract\fR(1) and examined using
16 \fBtnfdump\fR(1).
17 .sp
18 .LP
19 Each probe has a \fIname\fR and is associated with a set of symbolic
20 \fIkeys\fR, or \fIcategories\fR. These are used to select and control probes
21 from \fBprex\fR(1). A probe that is enabled for tracing generates a \fBTNF\fR
22 record, called an \fIevent record\fR. An event record contains two common
23 members and may contain other probe-specific data members.
24 .SS "Common Members"
25 .sp
26 .in +2
27 .nf
28 \fBtnf_probe_event\fR \fItag\fR
29 \fBtnf_time_delta\fR \fItime_delta\fR
30 .fi
31 .in -2
32
33 .sp
34 .ne 2
35 .na
36 \fB\fItag\fR\fR
37 .ad
38 .RS 14n
39 Encodes \fBTNF\fR references to two other records:
40 .sp
41 .ne 2
42 .na
43 \fB\fItag\fR\fR
44 .ad
45 .RS 12n
53 .ad
54 .RS 12n
55 Identifies the writing thread and also contains a 64-bit base time in
56 nanoseconds.
57 .RE
58
59 .RE
60
61 .sp
62 .ne 2
63 .na
64 \fB\fItime_delta\fR\fR
65 .ad
66 .RS 14n
67 A 32-bit time offset from the base time; the sum of the two times is the actual
68 time of the event.
69 .RE
70
71 .SS "Threads"
72 .SS "\fBthread_create\fR"
73 .sp
74 .in +2
75 .nf
76 \fBtnf_kthread_id\fR \fItid\fR
77 \fBtnf_pid\fR \fIpid\fR
78 \fBtnf_symbol\fR \fIstart_pc\fR
79 .fi
80 .in -2
81
82 .sp
83 .LP
84 Thread creation event.
85 .sp
86 .ne 2
87 .na
88 \fB\fItid\fR\fR
89 .ad
90 .RS 12n
91 The thread identifier for the new thread.
92 .RE
93
94 .sp
95 .ne 2
96 .na
97 \fB\fIpid\fR\fR
98 .ad
99 .RS 12n
100 The process identifier for the new thread.
101 .RE
102
103 .sp
104 .ne 2
105 .na
106 \fB\fIstart_pc\fR\fR
107 .ad
108 .RS 12n
109 The kernel address of its start routine.
110 .RE
111
112 .SS "\fBthread_state\fR"
113 .sp
114 .in +2
115 .nf
116 \fBtnf_kthread_id\fR \fItid\fR
117 \fBtnf_microstate\fR \fIstate\fR
118 .fi
119 .in -2
120
121 .sp
122 .LP
123 Thread microstate transition events.
124 .sp
125 .ne 2
126 .na
127 \fB\fItid\fR\fR
128 .ad
129 .RS 9n
130 Optional; if it is absent, the event is for the writing thread, otherwise the
131 event is for the specified thread.
132 .RE
133
164 .RE
165 .RS +4
166 .TP
167 .ie t \(bu
168 .el o
169 Runnable (waiting for a cpu).
170 .RE
171 .RS +4
172 .TP
173 .ie t \(bu
174 .el o
175 Stopped.
176 .RE
177 The values of this member are defined in <\fBsys/msacct.h\fR>. Note that to
178 reduce trace output, transitions between the \fIsystem\fR and \fIuser\fR
179 microstates that are induced by system calls are not traced. This information
180 is implicit in the system call entry and exit events.
181 .RE
182
183 .SS "thread_exit"
184 .sp
185 .LP
186 Thread termination event for writing thread. This probe has no data members
187 other than the common members.
188 .SS "Scheduling"
189 .sp
190 .LP
191 \fB\fR
192 .SS "thread_queue"
193 .sp
194 .in +2
195 .nf
196 \fBtnf_kthread_id\fR \fItid\fR
197 \fBtnf_cpuid\fR \fIcpuid\fR
198 \fBtnf_long\fR \fIpriority\fR
199 \fBtnf_ulong\fR \fIqueue_length\fR
200 .fi
201 .in -2
202
203 .sp
204 .LP
205 Thread scheduling events. These are triggered when a runnable thread is placed
206 on a dispatch queue.
207 .sp
208 .ne 2
209 .na
210 \fB\fIcpuid\fR\fR
211 .ad
212 .RS 16n
213 Specifies the cpu to which the queue is attached.
216 .sp
217 .ne 2
218 .na
219 \fB\fIpriority\fR\fR
220 .ad
221 .RS 16n
222 The (global) dispatch priority of the thread.
223 .RE
224
225 .sp
226 .ne 2
227 .na
228 \fB\fIqueue_length\fR\fR
229 .ad
230 .RS 16n
231 The current length of the cpu's dispatch queue.
232 .RE
233
234 .SS "Blocking"
235 .SS "\fBthread_block\fR"
236 .sp
237 .in +2
238 .nf
239 \fBtnf_opaque\fR \fIreason\fR
240 \fBtnf_symbols\fR \fIstack\fR
241 .fi
242 .in -2
243
244 .sp
245 .LP
246 Thread blockage event. This probe captures a partial stack backtrace when the
247 current thread blocks.
248 .sp
249 .ne 2
250 .na
251 \fB\fIreason\fR\fR
252 .ad
253 .RS 11n
254 The address of the object on which the thread is blocking.
255 .RE
256
257 .sp
258 .ne 2
259 .na
260 \fB\fIsymbols\fR\fR
261 .ad
262 .RS 11n
263 References a \fBTNF\fR array of kernel addresses representing the PCs on the
264 stack at the time the thread blocks.
265 .RE
266
267 .SS "System Calls"
268 .SS "\fBsyscall_start\fR"
269 .sp
270 .in +2
271 .nf
272 \fBtnf_sysnum\fR \fIsysnum\fR
273 .fi
274 .in -2
275
276 .sp
277 .LP
278 System call entry event.
279 .sp
280 .ne 2
281 .na
282 \fB\fIsysnum\fR\fR
283 .ad
284 .RS 10n
285 The system call number. The writing thread implicitly enters the \fIsystem\fR
286 microstate with this event.
287 .RE
288
289 .SS "\fBsyscall_end\fR"
290 .sp
291 .in +2
292 .nf
293 \fBtnf_long\fR \fIrval1\fR
294 \fBtnf_long\fR \fIrval2\fR
295 \fBtnf_long\fR \fIerrno\fR
296 .fi
297 .in -2
298
299 .sp
300 .LP
301 System call exit event.
302 .sp
303 .ne 2
304 .na
305 \fB\fIrval1\fR and \fIrval2\fR\fR
306 .ad
307 .RS 19n
308 The two return values of the system call
309 .RE
310
311 .sp
312 .ne 2
313 .na
314 \fB\fIerrno\fR\fR
315 .ad
316 .RS 19n
317 The error return.
318 .RE
319
320 .sp
321 .LP
322 The writing thread implicitly enters the \fIuser\fR microstate with this event.
323 .SS "Page Faults"
324 .SS "\fBaddress_fault\fR"
325 .sp
326 .in +2
327 .nf
328 \fBtnf_opaque\fR \fIaddress\fR
329 \fBtnf_fault_type\fR \fIfault_type\fR
330 \fBtnf_seg_access\fR \fIaccess\fR
331 .fi
332 .in -2
333
334 .sp
335 .LP
336 Address-space fault event.
337 .sp
338 .ne 2
339 .na
340 \fB\fIaddress\fR\fR
341 .ad
342 .RS 14n
343 Gives the faulting virtual address.
344 .RE
345
347 .ne 2
348 .na
349 \fB\fIfault_type\fR\fR
350 .ad
351 .RS 14n
352 Gives the fault type: invalid page, protection fault, software requested
353 locking or unlocking.
354 .RE
355
356 .sp
357 .ne 2
358 .na
359 \fB\fIaccess\fR\fR
360 .ad
361 .RS 14n
362 Gives the desired access protection: read, write, execute or create. The values
363 for these two members are defined in <\fBvm/seg_enum.h\fR>.
364 .RE
365
366 .SS "\fBmajor_fault\fR"
367 .sp
368 .in +2
369 .nf
370 \fBtnf_opaque\fR \fIvnode\fR
371 \fBtnf_offset\fR \fIoffset\fR
372 .fi
373 .in -2
374
375 .sp
376 .LP
377 Major page fault event. The faulting page is mapped to the file given by the
378 \fIvnode\fR member, at the given \fIoffset\fR into the file. (The faulting
379 virtual address is in the most recent \fBaddress_fault\fR event for the writing
380 thread.)
381 .SS "\fBanon_private\fR"
382 .sp
383 .in +2
384 .nf
385 \fBtnf_opaque\fR \fIaddress\fR
386 .fi
387 .in -2
388
389 .sp
390 .LP
391 Copy-on-write page fault event.
392 .sp
393 .ne 2
394 .na
395 \fB\fIaddress\fR\fR
396 .ad
397 .RS 11n
398 The virtual address at which the new page is mapped.
399 .RE
400
401 .SS "\fBanon_zero\fR"
402 .sp
403 .in +2
404 .nf
405 \fBtnf_opaque\fR \fIaddress\fR
406 .fi
407 .in -2
408
409 .sp
410 .LP
411 Zero-fill page fault event.
412 .sp
413 .ne 2
414 .na
415 \fB\fIaddress\fR\fR
416 .ad
417 .RS 11n
418 The virtual address at which the new page is mapped.
419 .RE
420
421 .SS "\fBpage_unmap\fR"
422 .sp
423 .in +2
424 .nf
425 \fBtnf_opaque\fR \fIvnode\fR
426 \fBtnf_offset\fR \fIoffset\fR
427 .fi
428 .in -2
429
430 .sp
431 .LP
432 Page unmapping event. This probe marks the unmapping of a file system page
433 from the system.
434 .sp
435 .ne 2
436 .na
437 \fB\fIvnode\fR and \fIoffset\fR\fR
438 .ad
439 .RS 20n
440 Identifies the file and offset of the page being unmapped.
441 .RE
442
443 .SS "Pageins and Pageouts"
444 .SS "\fBpagein\fR"
445 .sp
446 .in +2
447 .nf
448 \fBtnf_opaque\fR \fIvnode\fR
449 \fBtnf_offset\fR \fIoffset\fR
450 \fBtnf_size\fR \fIsize\fR
451 .fi
452 .in -2
453
454 .sp
455 .LP
456 Pagein start event. This event signals the initiation of pagein I/O.
457 .sp
458 .ne 2
459 .na
460 \fB\fIvnode\fRand\fIoffset\fR\fR
461 .ad
462 .RS 18n
463 Identifyies the file and offset to be paged in.
464 .RE
465
466 .sp
467 .ne 2
468 .na
469 \fB\fIsize\fR\fR
470 .ad
471 .RS 18n
472 Specifies the number of bytes to be paged in.
473 .RE
474
475 .SS "\fBpageout\fR"
476 .sp
477 .in +2
478 .nf
479 \fBtnf_opaque\fR \fIvnode\fR
480 \fBtnf_ulong\fR \fIpages_pageout\fR
481 \fBtnf_ulong\fR \fIpages_freed\fR
482 \fBtnf_ulong\fR \fIpages_reclaimed\fR
483 .fi
484 .in -2
485
486 .sp
487 .LP
488 Pageout completion event. This event signals the completion of pageout I/O.
489 .sp
490 .ne 2
491 .na
492 \fB\fIvnode\fR\fR
493 .ad
494 .RS 19n
495 Identifies the file of the pageout request.
496 .RE
507 .sp
508 .ne 2
509 .na
510 \fB\fIpages_freed\fR\fR
511 .ad
512 .RS 19n
513 The number of pages freed after being written out.
514 .RE
515
516 .sp
517 .ne 2
518 .na
519 \fB\fIpages_reclaimed\fR\fR
520 .ad
521 .RS 19n
522 The number of pages reclaimed after being written out.
523 .RE
524
525 .SS "Page Daemon (Page Stealer)"
526 .SS "\fBpageout_scan_start\fR"
527 .sp
528 .in +2
529 .nf
530 \fBtnf_ulong\fR \fIpages_free\fR
531 \fBtnf_ulong\fR \fIpages_needed\fR
532 .fi
533 .in -2
534
535 .sp
536 .LP
537 Page daemon scan start event. This event signals the beginning of one
538 iteration of the page daemon.
539 .sp
540 .ne 2
541 .na
542 \fB\fIpages_free\fR\fR
543 .ad
544 .RS 16n
545 The number of free pages in the system.
546 .RE
547
548 .sp
549 .ne 2
550 .na
551 \fB\fIpages_needed\fR\fR
552 .ad
553 .RS 16n
554 The number of pages desired free.
555 .RE
556
557 .SS "\fBpageout_scan_end\fR"
558 .sp
559 .in +2
560 .nf
561 \fBtnf_ulong\fR \fIpages_free\fR
562 \fBtnf_ulong\fR \fIpages_scanned\fR
563 .fi
564 .in -2
565
566 .sp
567 .LP
568 Page daemon scan end event. This event signals the end of one iteration of the
569 page daemon.
570 .sp
571 .ne 2
572 .na
573 \fB\fIpages_free\fR\fR
574 .ad
575 .RS 17n
576 The number of free pages in the system.
577 .RE
578
579 .sp
580 .ne 2
581 .na
582 \fB\fIpages_scanned\fR\fR
583 .ad
584 .RS 17n
585 The number of pages examined by the page daemon. (Potentially more pages will
586 be freed when any queued pageout requests complete.)
587 .RE
588
589 .SS "Swapper"
590 .SS "\fBswapout_process\fR"
591 .sp
592 .in +2
593 .nf
594 \fBtnf_pid\fR \fIpid\fR
595 \fBtnf_ulong\fR \fIpage_count\fR
596 .fi
597 .in -2
598
599 .sp
600 .LP
601 Address space swapout event. This event marks the swapping out of a process
602 address space.
603 .sp
604 .ne 2
605 .na
606 \fB\fIpid\fR\fR
607 .ad
608 .RS 14n
609 Identifies the process.
610 .RE
611
612 .sp
613 .ne 2
614 .na
615 \fB\fIpage_count\fR\fR
616 .ad
617 .RS 14n
618 Reports the number of pages either freed or queued for pageout.
619 .RE
620
621 .SS "\fBswapout_lwp\fR"
622 .sp
623 .in +2
624 .nf
625 \fBtnf_pid\fR \fIpid\fR
626 \fBtnf_lwpid\fR \fIlwpid\fR
627 \fBtnf_kthread_id\fR \fItid\fR
628 \fBtnf_ulong\fR \fIpage_count\fR
629 .fi
630 .in -2
631
632 .sp
633 .LP
634 Light-weight process swapout event. This event marks the swapping out of an
635 \fBLWP\fR and its stack.
636 .sp
637 .ne 2
638 .na
639 \fB\fIpid\fR\fR
640 .ad
641 .RS 14n
642 The \fBLWP's\fR process identifier
653
654 .sp
655 .ne 2
656 .na
657 \fB\fItid\fR \fImember\fR\fR
658 .ad
659 .RS 14n
660 The \fBLWP's\fR kernel thread identifier.
661 .RE
662
663 .sp
664 .ne 2
665 .na
666 \fB\fIpage_count\fR\fR
667 .ad
668 .RS 14n
669 The number of pages swapped out.
670 .RE
671
672 .SS "\fBswapin_lwp\fR"
673 .sp
674 .in +2
675 .nf
676 \fBtnf_pid\fR \fIpid\fR
677 \fBtnf_lwpid\fR \fIlwpid\fR
678 \fBtnf_kthread_id\fR \fItid\fR
679 \fBtnf_ulong\fR \fIpage_count\fR
680 .fi
681 .in -2
682
683 .sp
684 .LP
685 Light-weight process swapin event. This event marks the swapping in of an
686 \fBLWP\fR and its stack.
687 .sp
688 .ne 2
689 .na
690 \fB\fIpid\fR\fR
691 .ad
692 .RS 14n
693 The \fBLWP's\fR process identifier.
705 .sp
706 .ne 2
707 .na
708 \fB\fItid\fR\fR
709 .ad
710 .RS 14n
711 The \fBLWP's\fR kernel thread identifier.
712 .RE
713
714 .sp
715 .ne 2
716 .na
717 \fB\fIpage_count\fR\fR
718 .ad
719 .RS 14n
720 The number of pages swapped in.
721 .RE
722
723 .SS "Local I/O"
724 .SS "\fBstrategy\fR"
725 .sp
726 .in +2
727 .nf
728 \fBtnf_device\fR \fIdevice\fR
729 \fBtnf_diskaddr\fR \fIblock\fR
730 \fBtnf_size\fR \fIsize\fR
731 \fBtnf_opaque\fR \fIbuf\fR
732 \fBtnf_bioflags\fR \fI flags\fR
733 .fi
734 .in -2
735
736 .sp
737 .LP
738 Block I/O strategy event. This event marks a call to the \fBstrategy\fR(9E)
739 function of a block device driver.
740 .sp
741 .ne 2
742 .na
743 \fB\fIdevice\fR\fR
744 .ad
745 .RS 10n
766
767 .sp
768 .ne 2
769 .na
770 \fB\fIbuf\fR\fR
771 .ad
772 .RS 10n
773 The kernel address of the \fBbuf\fR(9S) structure associated with the transfer.
774 .RE
775
776 .sp
777 .ne 2
778 .na
779 \fB\fIflags\fR\fR
780 .ad
781 .RS 10n
782 The \fBbuf\fR(9S) flags associated with the transfer.
783 .RE
784
785 .SS "\fBbiodone\fR"
786 .sp
787 .in +2
788 .nf
789 \fBtnf_device\fR \fIdevice\fR
790 \fBtnf_diskaddr\fR \fIblock\fR
791 \fBtnf_opaque\fR \fIbuf\fR
792 .fi
793 .in -2
794
795 .sp
796 .LP
797 Buffered I/O completion event. This event marks calls to the \fBbiodone\fR(9F)
798 function.
799 .sp
800 .ne 2
801 .na
802 \fB\fIdevice\fR\fR
803 .ad
804 .RS 10n
805 Contains the major and minor numbers of the device.
806 .RE
807
808 .sp
809 .ne 2
810 .na
811 \fB\fIblock\fR\fR
812 .ad
813 .RS 10n
814 The logical block number accessed on the device.
815 .RE
816
817 .sp
818 .ne 2
819 .na
820 \fB\fIbuf\fR\fR
821 .ad
822 .RS 10n
823 The kernel address of the \fBbuf\fR(9S) structure associated with the transfer.
824 .RE
825
826 .SS "\fBphysio_start\fR"
827 .sp
828 .in +2
829 .nf
830 \fBtnf_device\fR \fIdevice\fR
831 \fBtnf_offset\fR \fIoffset\fR
832 \fBtnf_size\fR \fIsize\fR
833 \fBtnf_bioflags\fR \fIrw\fR
834 .fi
835 .in -2
836
837 .sp
838 .LP
839 Raw I/O start event. This event marks entry into the \fBphysio\fR(9F)
840 fufnction which performs unbuffered I/O.
841 .sp
842 .ne 2
843 .na
844 \fB\fIdevice\fR\fR
845 .ad
846 .RS 10n
847 Contains the major and minor numbers of the device of the transfer.
848 .RE
849
850 .sp
851 .ne 2
852 .na
853 \fB\fIoffset\fR\fR
854 .ad
855 .RS 10n
856 The logical offset on the device for the transfer.
857 .RE
858
859 .sp
860 .ne 2
861 .na
862 \fB\fIsize\fR\fR
863 .ad
864 .RS 10n
865 The number of bytes to be transferred.
866 .RE
867
868 .sp
869 .ne 2
870 .na
871 \fB\fIrw\fR\fR
872 .ad
873 .RS 10n
874 The direction of the transfer: read or write (see \fBbuf\fR(9S)).
875 .RE
876
877 .SS "\fBphysio_end\fR"
878 .sp
879 .in +2
880 .nf
881 \fBtnf_device\fR \fIdevice\fR
882 .fi
883 .in -2
884
885 .sp
886 .LP
887 Raw I/O end event. This event marks exit from the \fBphysio\fR(9F) fufnction.
888 .sp
889 .ne 2
890 .na
891 \fB\fIdevice\fR\fR
892 .ad
893 .RS 10n
894 The major and minor numbers of the device of the transfer.
895 .RE
896
897 .SH USAGE
898 .sp
899 .LP
900 Use the \fBprex\fR utility to control kernel probes. The standard \fBprex\fR
901 commands to list and manipulate probes are available to you, along with
902 commands to set up and manage kernel tracing.
903 .sp
904 .LP
905 Kernel probes write trace records into a kernel trace buffer. You must copy the
906 buffer into a TNF file for post-processing; use the \fBtnfxtract\fR utility for
907 this.
908 .sp
909 .LP
910 You use the \fBtnfdump\fR utility to examine a kernel trace file. This is
911 exactly the same as examining a user-level trace file.
912 .sp
913 .LP
914 The steps you typically follow to take a kernel trace are:
915 .RS +4
916 .TP
917 1.
918 Become superuser (\fBsu\fR).
919 .RE
951 .TP
952 8.
953 Disable all probes (\fBprex\fR).
954 .RE
955 .RS +4
956 .TP
957 9.
958 Deallocate the kernel trace buffer (\fBprex\fR).
959 .RE
960 .RS +4
961 .TP
962 10.
963 Examine the trace file (\fBtnfdump\fR).
964 .RE
965 .sp
966 .LP
967 A convenient way to follow these steps is to use two shell windows; run an
968 interactive \fBprex\fR session in one, and run your application and
969 \fBtnfxtract\fR in the other.
970 .SH SEE ALSO
971 .sp
972 .LP
973 \fBprex\fR(1), \fBtnfdump\fR(1), \fBtnfxtract\fR(1), \fBlibtnfctl\fR(3TNF),
974 \fBTNF_PROBE\fR(3TNF), \fBtracing\fR(3TNF), \fBstrategy\fR(9E),
975 \fBbiodone\fR(9F), \fBphysio\fR(9F), \fBbuf\fR(9S)
|
1 '\" te
2 .\" Copyright 1999 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 TNF_KERNEL_PROBES 4 "May 16, 2020"
7 .SH NAME
8 tnf_kernel_probes \- TNF kernel probes
9 .SH DESCRIPTION
10 The set of probes (trace instrumentation points) available in the standard
11 kernel. The probes log trace data to a kernel trace buffer in Trace Normal
12 Form (TNF). Kernel probes are controlled by \fBprex\fR(1). A snapshot of the
13 kernel trace buffer can be made using \fBtnfxtract\fR(1) and examined using
14 \fBtnfdump\fR(1).
15 .sp
16 .LP
17 Each probe has a \fIname\fR and is associated with a set of symbolic
18 \fIkeys\fR, or \fIcategories\fR. These are used to select and control probes
19 from \fBprex\fR(1). A probe that is enabled for tracing generates a \fBTNF\fR
20 record, called an \fIevent record\fR. An event record contains two common
21 members and may contain other probe-specific data members.
22 .SS "Common Members"
23 .in +2
24 .nf
25 \fBtnf_probe_event\fR \fItag\fR
26 \fBtnf_time_delta\fR \fItime_delta\fR
27 .fi
28 .in -2
29
30 .sp
31 .ne 2
32 .na
33 \fB\fItag\fR\fR
34 .ad
35 .RS 14n
36 Encodes \fBTNF\fR references to two other records:
37 .sp
38 .ne 2
39 .na
40 \fB\fItag\fR\fR
41 .ad
42 .RS 12n
50 .ad
51 .RS 12n
52 Identifies the writing thread and also contains a 64-bit base time in
53 nanoseconds.
54 .RE
55
56 .RE
57
58 .sp
59 .ne 2
60 .na
61 \fB\fItime_delta\fR\fR
62 .ad
63 .RS 14n
64 A 32-bit time offset from the base time; the sum of the two times is the actual
65 time of the event.
66 .RE
67
68 .SS "Threads"
69 .SS "\fBthread_create\fR"
70 .in +2
71 .nf
72 \fBtnf_kthread_id\fR \fItid\fR
73 \fBtnf_pid\fR \fIpid\fR
74 \fBtnf_symbol\fR \fIstart_pc\fR
75 .fi
76 .in -2
77
78 .sp
79 .LP
80 Thread creation event.
81 .sp
82 .ne 2
83 .na
84 \fB\fItid\fR\fR
85 .ad
86 .RS 12n
87 The thread identifier for the new thread.
88 .RE
89
90 .sp
91 .ne 2
92 .na
93 \fB\fIpid\fR\fR
94 .ad
95 .RS 12n
96 The process identifier for the new thread.
97 .RE
98
99 .sp
100 .ne 2
101 .na
102 \fB\fIstart_pc\fR\fR
103 .ad
104 .RS 12n
105 The kernel address of its start routine.
106 .RE
107
108 .SS "\fBthread_state\fR"
109 .in +2
110 .nf
111 \fBtnf_kthread_id\fR \fItid\fR
112 \fBtnf_microstate\fR \fIstate\fR
113 .fi
114 .in -2
115
116 .sp
117 .LP
118 Thread microstate transition events.
119 .sp
120 .ne 2
121 .na
122 \fB\fItid\fR\fR
123 .ad
124 .RS 9n
125 Optional; if it is absent, the event is for the writing thread, otherwise the
126 event is for the specified thread.
127 .RE
128
159 .RE
160 .RS +4
161 .TP
162 .ie t \(bu
163 .el o
164 Runnable (waiting for a cpu).
165 .RE
166 .RS +4
167 .TP
168 .ie t \(bu
169 .el o
170 Stopped.
171 .RE
172 The values of this member are defined in <\fBsys/msacct.h\fR>. Note that to
173 reduce trace output, transitions between the \fIsystem\fR and \fIuser\fR
174 microstates that are induced by system calls are not traced. This information
175 is implicit in the system call entry and exit events.
176 .RE
177
178 .SS "thread_exit"
179 Thread termination event for writing thread. This probe has no data members
180 other than the common members.
181 .SS "Scheduling"
182 \fB\fR
183 .SS "thread_queue"
184 .in +2
185 .nf
186 \fBtnf_kthread_id\fR \fItid\fR
187 \fBtnf_cpuid\fR \fIcpuid\fR
188 \fBtnf_long\fR \fIpriority\fR
189 \fBtnf_ulong\fR \fIqueue_length\fR
190 .fi
191 .in -2
192
193 .sp
194 .LP
195 Thread scheduling events. These are triggered when a runnable thread is placed
196 on a dispatch queue.
197 .sp
198 .ne 2
199 .na
200 \fB\fIcpuid\fR\fR
201 .ad
202 .RS 16n
203 Specifies the cpu to which the queue is attached.
206 .sp
207 .ne 2
208 .na
209 \fB\fIpriority\fR\fR
210 .ad
211 .RS 16n
212 The (global) dispatch priority of the thread.
213 .RE
214
215 .sp
216 .ne 2
217 .na
218 \fB\fIqueue_length\fR\fR
219 .ad
220 .RS 16n
221 The current length of the cpu's dispatch queue.
222 .RE
223
224 .SS "Blocking"
225 .SS "\fBthread_block\fR"
226 .in +2
227 .nf
228 \fBtnf_opaque\fR \fIreason\fR
229 \fBtnf_symbols\fR \fIstack\fR
230 .fi
231 .in -2
232
233 .sp
234 .LP
235 Thread blockage event. This probe captures a partial stack backtrace when the
236 current thread blocks.
237 .sp
238 .ne 2
239 .na
240 \fB\fIreason\fR\fR
241 .ad
242 .RS 11n
243 The address of the object on which the thread is blocking.
244 .RE
245
246 .sp
247 .ne 2
248 .na
249 \fB\fIsymbols\fR\fR
250 .ad
251 .RS 11n
252 References a \fBTNF\fR array of kernel addresses representing the PCs on the
253 stack at the time the thread blocks.
254 .RE
255
256 .SS "System Calls"
257 .SS "\fBsyscall_start\fR"
258 .in +2
259 .nf
260 \fBtnf_sysnum\fR \fIsysnum\fR
261 .fi
262 .in -2
263
264 .sp
265 .LP
266 System call entry event.
267 .sp
268 .ne 2
269 .na
270 \fB\fIsysnum\fR\fR
271 .ad
272 .RS 10n
273 The system call number. The writing thread implicitly enters the \fIsystem\fR
274 microstate with this event.
275 .RE
276
277 .SS "\fBsyscall_end\fR"
278 .in +2
279 .nf
280 \fBtnf_long\fR \fIrval1\fR
281 \fBtnf_long\fR \fIrval2\fR
282 \fBtnf_long\fR \fIerrno\fR
283 .fi
284 .in -2
285
286 .sp
287 .LP
288 System call exit event.
289 .sp
290 .ne 2
291 .na
292 \fB\fIrval1\fR and \fIrval2\fR\fR
293 .ad
294 .RS 19n
295 The two return values of the system call
296 .RE
297
298 .sp
299 .ne 2
300 .na
301 \fB\fIerrno\fR\fR
302 .ad
303 .RS 19n
304 The error return.
305 .RE
306
307 .sp
308 .LP
309 The writing thread implicitly enters the \fIuser\fR microstate with this event.
310 .SS "Page Faults"
311 .SS "\fBaddress_fault\fR"
312 .in +2
313 .nf
314 \fBtnf_opaque\fR \fIaddress\fR
315 \fBtnf_fault_type\fR \fIfault_type\fR
316 \fBtnf_seg_access\fR \fIaccess\fR
317 .fi
318 .in -2
319
320 .sp
321 .LP
322 Address-space fault event.
323 .sp
324 .ne 2
325 .na
326 \fB\fIaddress\fR\fR
327 .ad
328 .RS 14n
329 Gives the faulting virtual address.
330 .RE
331
333 .ne 2
334 .na
335 \fB\fIfault_type\fR\fR
336 .ad
337 .RS 14n
338 Gives the fault type: invalid page, protection fault, software requested
339 locking or unlocking.
340 .RE
341
342 .sp
343 .ne 2
344 .na
345 \fB\fIaccess\fR\fR
346 .ad
347 .RS 14n
348 Gives the desired access protection: read, write, execute or create. The values
349 for these two members are defined in <\fBvm/seg_enum.h\fR>.
350 .RE
351
352 .SS "\fBmajor_fault\fR"
353 .in +2
354 .nf
355 \fBtnf_opaque\fR \fIvnode\fR
356 \fBtnf_offset\fR \fIoffset\fR
357 .fi
358 .in -2
359
360 .sp
361 .LP
362 Major page fault event. The faulting page is mapped to the file given by the
363 \fIvnode\fR member, at the given \fIoffset\fR into the file. (The faulting
364 virtual address is in the most recent \fBaddress_fault\fR event for the writing
365 thread.)
366 .SS "\fBanon_private\fR"
367 .in +2
368 .nf
369 \fBtnf_opaque\fR \fIaddress\fR
370 .fi
371 .in -2
372
373 .sp
374 .LP
375 Copy-on-write page fault event.
376 .sp
377 .ne 2
378 .na
379 \fB\fIaddress\fR\fR
380 .ad
381 .RS 11n
382 The virtual address at which the new page is mapped.
383 .RE
384
385 .SS "\fBanon_zero\fR"
386 .in +2
387 .nf
388 \fBtnf_opaque\fR \fIaddress\fR
389 .fi
390 .in -2
391
392 .sp
393 .LP
394 Zero-fill page fault event.
395 .sp
396 .ne 2
397 .na
398 \fB\fIaddress\fR\fR
399 .ad
400 .RS 11n
401 The virtual address at which the new page is mapped.
402 .RE
403
404 .SS "\fBpage_unmap\fR"
405 .in +2
406 .nf
407 \fBtnf_opaque\fR \fIvnode\fR
408 \fBtnf_offset\fR \fIoffset\fR
409 .fi
410 .in -2
411
412 .sp
413 .LP
414 Page unmapping event. This probe marks the unmapping of a file system page
415 from the system.
416 .sp
417 .ne 2
418 .na
419 \fB\fIvnode\fR and \fIoffset\fR\fR
420 .ad
421 .RS 20n
422 Identifies the file and offset of the page being unmapped.
423 .RE
424
425 .SS "Pageins and Pageouts"
426 .SS "\fBpagein\fR"
427 .in +2
428 .nf
429 \fBtnf_opaque\fR \fIvnode\fR
430 \fBtnf_offset\fR \fIoffset\fR
431 \fBtnf_size\fR \fIsize\fR
432 .fi
433 .in -2
434
435 .sp
436 .LP
437 Pagein start event. This event signals the initiation of pagein I/O.
438 .sp
439 .ne 2
440 .na
441 \fB\fIvnode\fRand\fIoffset\fR\fR
442 .ad
443 .RS 18n
444 Identifies the file and offset to be paged in.
445 .RE
446
447 .sp
448 .ne 2
449 .na
450 \fB\fIsize\fR\fR
451 .ad
452 .RS 18n
453 Specifies the number of bytes to be paged in.
454 .RE
455
456 .SS "\fBpageout\fR"
457 .in +2
458 .nf
459 \fBtnf_opaque\fR \fIvnode\fR
460 \fBtnf_ulong\fR \fIpages_pageout\fR
461 \fBtnf_ulong\fR \fIpages_freed\fR
462 \fBtnf_ulong\fR \fIpages_reclaimed\fR
463 .fi
464 .in -2
465
466 .sp
467 .LP
468 Pageout completion event. This event signals the completion of pageout I/O.
469 .sp
470 .ne 2
471 .na
472 \fB\fIvnode\fR\fR
473 .ad
474 .RS 19n
475 Identifies the file of the pageout request.
476 .RE
487 .sp
488 .ne 2
489 .na
490 \fB\fIpages_freed\fR\fR
491 .ad
492 .RS 19n
493 The number of pages freed after being written out.
494 .RE
495
496 .sp
497 .ne 2
498 .na
499 \fB\fIpages_reclaimed\fR\fR
500 .ad
501 .RS 19n
502 The number of pages reclaimed after being written out.
503 .RE
504
505 .SS "Page Daemon (Page Stealer)"
506 .SS "\fBpageout_scan_start\fR"
507 .in +2
508 .nf
509 \fBtnf_ulong\fR \fIpages_free\fR
510 \fBtnf_ulong\fR \fIpages_needed\fR
511 .fi
512 .in -2
513
514 .sp
515 .LP
516 Page daemon scan start event. This event signals the beginning of one
517 iteration of the page daemon.
518 .sp
519 .ne 2
520 .na
521 \fB\fIpages_free\fR\fR
522 .ad
523 .RS 16n
524 The number of free pages in the system.
525 .RE
526
527 .sp
528 .ne 2
529 .na
530 \fB\fIpages_needed\fR\fR
531 .ad
532 .RS 16n
533 The number of pages desired free.
534 .RE
535
536 .SS "\fBpageout_scan_end\fR"
537 .in +2
538 .nf
539 \fBtnf_ulong\fR \fIpages_free\fR
540 \fBtnf_ulong\fR \fIpages_scanned\fR
541 .fi
542 .in -2
543
544 .sp
545 .LP
546 Page daemon scan end event. This event signals the end of one iteration of the
547 page daemon.
548 .sp
549 .ne 2
550 .na
551 \fB\fIpages_free\fR\fR
552 .ad
553 .RS 17n
554 The number of free pages in the system.
555 .RE
556
557 .sp
558 .ne 2
559 .na
560 \fB\fIpages_scanned\fR\fR
561 .ad
562 .RS 17n
563 The number of pages examined by the page daemon. (Potentially more pages will
564 be freed when any queued pageout requests complete.)
565 .RE
566
567 .SS "Swapper"
568 .SS "\fBswapout_process\fR"
569 .in +2
570 .nf
571 \fBtnf_pid\fR \fIpid\fR
572 \fBtnf_ulong\fR \fIpage_count\fR
573 .fi
574 .in -2
575
576 .sp
577 .LP
578 Address space swapout event. This event marks the swapping out of a process
579 address space.
580 .sp
581 .ne 2
582 .na
583 \fB\fIpid\fR\fR
584 .ad
585 .RS 14n
586 Identifies the process.
587 .RE
588
589 .sp
590 .ne 2
591 .na
592 \fB\fIpage_count\fR\fR
593 .ad
594 .RS 14n
595 Reports the number of pages either freed or queued for pageout.
596 .RE
597
598 .SS "\fBswapout_lwp\fR"
599 .in +2
600 .nf
601 \fBtnf_pid\fR \fIpid\fR
602 \fBtnf_lwpid\fR \fIlwpid\fR
603 \fBtnf_kthread_id\fR \fItid\fR
604 \fBtnf_ulong\fR \fIpage_count\fR
605 .fi
606 .in -2
607
608 .sp
609 .LP
610 Light-weight process swapout event. This event marks the swapping out of an
611 \fBLWP\fR and its stack.
612 .sp
613 .ne 2
614 .na
615 \fB\fIpid\fR\fR
616 .ad
617 .RS 14n
618 The \fBLWP's\fR process identifier
629
630 .sp
631 .ne 2
632 .na
633 \fB\fItid\fR \fImember\fR\fR
634 .ad
635 .RS 14n
636 The \fBLWP's\fR kernel thread identifier.
637 .RE
638
639 .sp
640 .ne 2
641 .na
642 \fB\fIpage_count\fR\fR
643 .ad
644 .RS 14n
645 The number of pages swapped out.
646 .RE
647
648 .SS "\fBswapin_lwp\fR"
649 .in +2
650 .nf
651 \fBtnf_pid\fR \fIpid\fR
652 \fBtnf_lwpid\fR \fIlwpid\fR
653 \fBtnf_kthread_id\fR \fItid\fR
654 \fBtnf_ulong\fR \fIpage_count\fR
655 .fi
656 .in -2
657
658 .sp
659 .LP
660 Light-weight process swapin event. This event marks the swapping in of an
661 \fBLWP\fR and its stack.
662 .sp
663 .ne 2
664 .na
665 \fB\fIpid\fR\fR
666 .ad
667 .RS 14n
668 The \fBLWP's\fR process identifier.
680 .sp
681 .ne 2
682 .na
683 \fB\fItid\fR\fR
684 .ad
685 .RS 14n
686 The \fBLWP's\fR kernel thread identifier.
687 .RE
688
689 .sp
690 .ne 2
691 .na
692 \fB\fIpage_count\fR\fR
693 .ad
694 .RS 14n
695 The number of pages swapped in.
696 .RE
697
698 .SS "Local I/O"
699 .SS "\fBstrategy\fR"
700 .in +2
701 .nf
702 \fBtnf_device\fR \fIdevice\fR
703 \fBtnf_diskaddr\fR \fIblock\fR
704 \fBtnf_size\fR \fIsize\fR
705 \fBtnf_opaque\fR \fIbuf\fR
706 \fBtnf_bioflags\fR \fI flags\fR
707 .fi
708 .in -2
709
710 .sp
711 .LP
712 Block I/O strategy event. This event marks a call to the \fBstrategy\fR(9E)
713 function of a block device driver.
714 .sp
715 .ne 2
716 .na
717 \fB\fIdevice\fR\fR
718 .ad
719 .RS 10n
740
741 .sp
742 .ne 2
743 .na
744 \fB\fIbuf\fR\fR
745 .ad
746 .RS 10n
747 The kernel address of the \fBbuf\fR(9S) structure associated with the transfer.
748 .RE
749
750 .sp
751 .ne 2
752 .na
753 \fB\fIflags\fR\fR
754 .ad
755 .RS 10n
756 The \fBbuf\fR(9S) flags associated with the transfer.
757 .RE
758
759 .SS "\fBbiodone\fR"
760 .in +2
761 .nf
762 \fBtnf_device\fR \fIdevice\fR
763 \fBtnf_diskaddr\fR \fIblock\fR
764 \fBtnf_opaque\fR \fIbuf\fR
765 .fi
766 .in -2
767
768 .sp
769 .LP
770 Buffered I/O completion event. This event marks calls to the \fBbiodone\fR(9F)
771 function.
772 .sp
773 .ne 2
774 .na
775 \fB\fIdevice\fR\fR
776 .ad
777 .RS 10n
778 Contains the major and minor numbers of the device.
779 .RE
780
781 .sp
782 .ne 2
783 .na
784 \fB\fIblock\fR\fR
785 .ad
786 .RS 10n
787 The logical block number accessed on the device.
788 .RE
789
790 .sp
791 .ne 2
792 .na
793 \fB\fIbuf\fR\fR
794 .ad
795 .RS 10n
796 The kernel address of the \fBbuf\fR(9S) structure associated with the transfer.
797 .RE
798
799 .SS "\fBphysio_start\fR"
800 .in +2
801 .nf
802 \fBtnf_device\fR \fIdevice\fR
803 \fBtnf_offset\fR \fIoffset\fR
804 \fBtnf_size\fR \fIsize\fR
805 \fBtnf_bioflags\fR \fIrw\fR
806 .fi
807 .in -2
808
809 .sp
810 .LP
811 Raw I/O start event. This event marks entry into the \fBphysio\fR(9F)
812 function which performs unbuffered I/O.
813 .sp
814 .ne 2
815 .na
816 \fB\fIdevice\fR\fR
817 .ad
818 .RS 10n
819 Contains the major and minor numbers of the device of the transfer.
820 .RE
821
822 .sp
823 .ne 2
824 .na
825 \fB\fIoffset\fR\fR
826 .ad
827 .RS 10n
828 The logical offset on the device for the transfer.
829 .RE
830
831 .sp
832 .ne 2
833 .na
834 \fB\fIsize\fR\fR
835 .ad
836 .RS 10n
837 The number of bytes to be transferred.
838 .RE
839
840 .sp
841 .ne 2
842 .na
843 \fB\fIrw\fR\fR
844 .ad
845 .RS 10n
846 The direction of the transfer: read or write (see \fBbuf\fR(9S)).
847 .RE
848
849 .SS "\fBphysio_end\fR"
850 .in +2
851 .nf
852 \fBtnf_device\fR \fIdevice\fR
853 .fi
854 .in -2
855
856 .sp
857 .LP
858 Raw I/O end event. This event marks exit from the \fBphysio\fR(9F) function.
859 .sp
860 .ne 2
861 .na
862 \fB\fIdevice\fR\fR
863 .ad
864 .RS 10n
865 The major and minor numbers of the device of the transfer.
866 .RE
867
868 .SH USAGE
869 Use the \fBprex\fR utility to control kernel probes. The standard \fBprex\fR
870 commands to list and manipulate probes are available to you, along with
871 commands to set up and manage kernel tracing.
872 .sp
873 .LP
874 Kernel probes write trace records into a kernel trace buffer. You must copy the
875 buffer into a TNF file for post-processing; use the \fBtnfxtract\fR utility for
876 this.
877 .sp
878 .LP
879 You use the \fBtnfdump\fR utility to examine a kernel trace file. This is
880 exactly the same as examining a user-level trace file.
881 .sp
882 .LP
883 The steps you typically follow to take a kernel trace are:
884 .RS +4
885 .TP
886 1.
887 Become superuser (\fBsu\fR).
888 .RE
920 .TP
921 8.
922 Disable all probes (\fBprex\fR).
923 .RE
924 .RS +4
925 .TP
926 9.
927 Deallocate the kernel trace buffer (\fBprex\fR).
928 .RE
929 .RS +4
930 .TP
931 10.
932 Examine the trace file (\fBtnfdump\fR).
933 .RE
934 .sp
935 .LP
936 A convenient way to follow these steps is to use two shell windows; run an
937 interactive \fBprex\fR session in one, and run your application and
938 \fBtnfxtract\fR in the other.
939 .SH SEE ALSO
940 \fBprex\fR(1), \fBtnfdump\fR(1), \fBtnfxtract\fR(1), \fBlibtnfctl\fR(3TNF),
941 \fBTNF_PROBE\fR(3TNF), \fBtracing\fR(3TNF), \fBstrategy\fR(9E),
942 \fBbiodone\fR(9F), \fBphysio\fR(9F), \fBbuf\fR(9S)
|