1tnf_kernel_probes(4) File Formats tnf_kernel_probes(4)
2
6 tnf_kernel_probes - TNF kernel probes
7
9 The set of probes (trace instrumentation points) available in the stan‐
10 dard kernel. The probes log trace data to a kernel trace buffer in
11 Trace Normal Form (TNF). Kernel probes are controlled by prex(1). A
12 snapshot of the kernel trace buffer can be made using tnfxtract(1) and
13 examined using tnfdump(1).
14 Each probe has a name and is associated with a set of symbolic keys, or
17 categories. These are used to select and control probes from prex(1). A
18 probe that is enabled for tracing generates a TNF record, called an
19 event record. An event record contains two common members and may con‐
20 tain other probe-specific data members.
21 Common Members
23 tnf_probe_event tag
24 tnf_time_delta time_delta
25 tag Encodes TNF references to two other records:
28 tag Describes the layout of the event record.
30 schedule Identifies the writing thread and also con‐
33 tains a 64-bit base time in nanoseconds.
34 time_delta A 32-bit time offset from the base time; the sum of the
38 two times is the actual time of the event.
39 Threads
42 thread_create
43 tnf_kthread_id tid
44 tnf_pid pid
45 tnf_symbol start_pc
46 Thread creation event.
50 tid The thread identifier for the new thread.
52 pid The process identifier for the new thread.
55 start_pc The kernel address of its start routine.
58 thread_state
61 tnf_kthread_id tid
62 tnf_microstate state
63 Thread microstate transition events.
67 tid Optional; if it is absent, the event is for the writing
69 thread, otherwise the event is for the specified thread.
70 state Indicates the thread state:
73 o Running in user mode.
75 o Running in system mode.
77 o Asleep waiting for a user-mode lock.
79 o Asleep on a kernel object.
81 o Runnable (waiting for a cpu).
83 o Stopped.
85 The values of this member are defined in <sys/msacct.h>. Note
86 that to reduce trace output, transitions between the system
87 and user microstates that are induced by system calls are not
88 traced. This information is implicit in the system call
89 entry and exit events.
90 thread_exit
93 Thread termination event for writing thread. This probe has no data
94 members other than the common members.
95 Scheduling
97 thread_queue
100 tnf_kthread_id tid
101 tnf_cpuid cpuid
102 tnf_long priority
103 tnf_ulong queue_length
104 Thread scheduling events. These are triggered when a runnable thread
108 is placed on a dispatch queue.
109 cpuid Specifies the cpu to which the queue is attached.
111 priority The (global) dispatch priority of the thread.
114 queue_length The current length of the cpu's dispatch queue.
117 Blocking
120 thread_block
121 tnf_opaque reason
122 tnf_symbols stack
123 Thread blockage event. This probe captures a partial stack backtrace
127 when the current thread blocks.
128 reason The address of the object on which the thread is blocking.
130 symbols References a TNF array of kernel addresses representing the
133 PCs on the stack at the time the thread blocks.
134 System Calls
137 syscall_start
138 tnf_sysnum sysnum
139 System call entry event.
143 sysnum The system call number. The writing thread implicitly enters
145 the system microstate with this event.
146 syscall_end
149 tnf_long rval1
150 tnf_long rval2
151 tnf_long errno
152 System call exit event.
156 rval1 and rval2 The two return values of the system call
158 errno The error return.
161 The writing thread implicitly enters the user microstate with this
165 event.
166 Page Faults
168 address_fault
169 tnf_opaque address
170 tnf_fault_type fault_type
171 tnf_seg_access access
172 Address-space fault event.
176 address Gives the faulting virtual address.
178 fault_type Gives the fault type: invalid page, protection fault,
181 software requested locking or unlocking.
182 access Gives the desired access protection: read, write, execute
185 or create. The values for these two members are defined
186 in <vm/seg_enum.h>.
187 major_fault
190 tnf_opaque vnode
191 tnf_offset offset
192 Major page fault event. The faulting page is mapped to the file given
196 by the vnode member, at the given offset into the file. (The faulting
197 virtual address is in the most recent address_fault event for the writ‐
198 ing thread.)
199 anon_private
201 tnf_opaque address
202 Copy-on-write page fault event.
206 address The virtual address at which the new page is mapped.
208 anon_zero
211 tnf_opaque address
212 Zero-fill page fault event.
216 address The virtual address at which the new page is mapped.
218 page_unmap
221 tnf_opaque vnode
222 tnf_offset offset
223 Page unmapping event. This probe marks the unmapping of a file system
227 page from the system.
228 vnode and offset Identifies the file and offset of the page being
230 unmapped.
231 Pageins and Pageouts
234 pagein
235 tnf_opaque vnode
236 tnf_offset offset
237 tnf_size size
238 Pagein start event. This event signals the initiation of pagein I/O.
242 vnodeandoffset Identifyies the file and offset to be paged in.
244 size Specifies the number of bytes to be paged in.
247 pageout
250 tnf_opaque vnode
251 tnf_ulong pages_pageout
252 tnf_ulong pages_freed
253 tnf_ulong pages_reclaimed
254 Pageout completion event. This event signals the completion of pageout
258 I/O.
259 vnode Identifies the file of the pageout request.
261 pages_pageout The number of pages written out.
264 pages_freed The number of pages freed after being written out.
267 pages_reclaimed The number of pages reclaimed after being written
270 out.
271 Page Daemon (Page Stealer)
274 pageout_scan_start
275 tnf_ulong pages_free
276 tnf_ulong pages_needed
277 Page daemon scan start event. This event signals the beginning of one
281 iteration of the page daemon.
282 pages_free The number of free pages in the system.
284 pages_needed The number of pages desired free.
287 pageout_scan_end
290 tnf_ulong pages_free
291 tnf_ulong pages_scanned
292 Page daemon scan end event. This event signals the end of one itera‐
296 tion of the page daemon.
297 pages_free The number of free pages in the system.
299 pages_scanned The number of pages examined by the page daemon.
302 (Potentially more pages will be freed when any queued
303 pageout requests complete.)
304 Swapper
307 swapout_process
308 tnf_pid pid
309 tnf_ulong page_count
310 Address space swapout event. This event marks the swapping out of a
314 process address space.
315 pid Identifies the process.
317 page_count Reports the number of pages either freed or queued for
320 pageout.
321 swapout_lwp
324 tnf_pid pid
325 tnf_lwpid lwpid
326 tnf_kthread_id tid
327 tnf_ulong page_count
328 Light-weight process swapout event. This event marks the swapping out
332 of an LWP and its stack.
333 pid The LWP's process identifier
335 lwpid The LWP identifier
338 tid member The LWP's kernel thread identifier.
341 page_count The number of pages swapped out.
344 swapin_lwp
347 tnf_pid pid
348 tnf_lwpid lwpid
349 tnf_kthread_id tid
350 tnf_ulong page_count
351 Light-weight process swapin event. This event marks the swapping in of
355 an LWP and its stack.
356 pid The LWP's process identifier.
358 lwpid The LWP identifier.
361 tid The LWP's kernel thread identifier.
364 page_count The number of pages swapped in.
367 Local I/O
370 strategy
371 tnf_device device
372 tnf_diskaddr block
373 tnf_size size
374 tnf_opaque buf
375 tnf_bioflags flags
376 Block I/O strategy event. This event marks a call to the strategy(9E)
380 function of a block device driver.
381 device Contains the major and minor numbers of the device.
383 block The logical block number to be accessed on the device.
386 size The size of the I/O request.
389 buf The kernel address of the buf(9S) structure associated with
392 the transfer.
393 flags The buf(9S) flags associated with the transfer.
396 biodone
399 tnf_device device
400 tnf_diskaddr block
401 tnf_opaque buf
402 Buffered I/O completion event. This event marks calls to the
406 biodone(9F) function.
407 device Contains the major and minor numbers of the device.
409 block The logical block number accessed on the device.
412 buf The kernel address of the buf(9S) structure associated with
415 the transfer.
416 physio_start
419 tnf_device device
420 tnf_offset offset
421 tnf_size size
422 tnf_bioflags rw
423 Raw I/O start event. This event marks entry into the physio(9F) fufnc‐
427 tion which performs unbuffered I/O.
428 device Contains the major and minor numbers of the device of the
430 transfer.
431 offset The logical offset on the device for the transfer.
434 size The number of bytes to be transferred.
437 rw The direction of the transfer: read or write (see buf(9S)).
440 physio_end
443 tnf_device device
444 Raw I/O end event. This event marks exit from the physio(9F) fufnc‐
448 tion.
449 device The major and minor numbers of the device of the transfer.
451
454 Use the prex utility to control kernel probes. The standard prex com‐
455 mands to list and manipulate probes are available to you, along with
456 commands to set up and manage kernel tracing.
457 Kernel probes write trace records into a kernel trace buffer. You must
460 copy the buffer into a TNF file for post-processing; use the tnfxtract
461 utility for this.
462 You use the tnfdump utility to examine a kernel trace file. This is
465 exactly the same as examining a user-level trace file.
466 The steps you typically follow to take a kernel trace are:
469 1. Become superuser (su).
471 2. Allocate a kernel trace buffer of the desired size (prex).
473 3. Select the probes you want to trace and enable (prex).
475 4. Turn kernel tracing on (prex).
477 5. Run your application.
479 6. Turn kernel tracing off (prex).
481 7. Extract the kernel trace buffer (tnfxtract).
483 8. Disable all probes (prex).
485 9. Deallocate the kernel trace buffer (prex).
487 10. Examine the trace file (tnfdump).
489 A convenient way to follow these steps is to use two shell windows; run
492 an interactive prex session in one, and run your application and tnfx‐
493 tract in the other.
494
496 prex(1), tnfdump(1), tnfxtract(1), libtnfctl(3TNF), TNF_PROBE(3TNF),
497 tracing(3TNF), strategy(9E), biodone(9F), physio(9F), buf(9S)
498SunOS 5.11 8 Nov1999 tnf_kernel_probes(4)