1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
|
.\" $OpenBSD: dt.4,v 1.9 2025/10/11 00:54:55 jsg Exp $
.\"
.\" Copyright (c) 2019 Martin Pieuchot <mpi@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: October 11 2025 $
.Dt DT 4
.Os
.Sh NAME
.Nm dt
.Nd dynamic tracer
.Sh SYNOPSIS
.Cd "pseudo-device dt"
.Sh DESCRIPTION
System and application tracing can happen in the kernel.
It has to be configured and enabled through the
.Xr ioctl 2
interface exposed by the pseudo-device
.Pa /dev/dt .
.Pp
This device can only be opened when the
.Va kern.allowdt
.Xr sysctl 2
variable is set.
.Sh IOCTL INTERFACE
The
.Xr ioctl 2
command codes below are defined in
.In dev/dt/dtvar.h .
.Bl -tag -width xxxxxx
.It Dv DTIOCGPLIST Fa "struct dtioc_probe *dtpr"
Get available probe entries.
.Bd -literal
struct dtioc_probe {
size_t dtpr_size;
struct dtioc_probe_info *dtpr_probes;
};
.Ed
.Pp
If
.Va dtpr_size
is non-zero, as many probes as possible that can fit into this size
will be copied into the supplied buffer.
On exit,
.Va dtpr_size
is always set to the total size required to hold all probe entries
(i.e., it is set to
.Li sizeof(struct dtioc_probe_info) * dt_nprobes ) .
.It Dv DTIOCGSTATS Fa "struct dtioc_stat *dtst"
Get statistics for current recording.
.Bd -literal
struct dtioc_stat {
uint64_t dtst_readevt;
uint64_t dtst_dropevt;
};
.Ed
.It Dv DTIOCRECORD Fa "int on"
Start or stop recording.
.It Dv DTIOCPRBENABLE Fa "struct dtioc_req *dtrq"
Enable the given probe for recording.
.Bd -literal
struct dtioc_req {
uint32_t dtrq_pbn;
struct dt_filter dtrq_filter;
uint32_t dtrq_rate;
uint64_t dtrq_evtflags;
};
.Ed
.It Dv DTIOCRDVNODE Fa "struct *dtioc_rdvn"
Resolve the instruction pointer from the traced process to the ELF object.
.Bd -literal
struct dtioc_rdvn {
pid_t dtrv_pid;
int dtrv_fd;
caddr_t dtrv_va;
caddr_t dtrv_offset;
caddr_t dtrv_start;
size_t dtrv_len;
};
.Ed
.Pp
The caller populates
.Fa dtrv_pid
with the process ID of the traced process and
.Fa dtrv_va
with the program counter address to look up.
.Pp
On success, the remaining members are populated.
.Fa dtrv_fd
is the file descriptor to the DSO file that
.Fa dtrv_va
belongs to.
.Fa dtrv_len
is the length of the DSO file.
.Fa dtrv_offset
and
.Fa dtrv_start
are the relative offset of
.Fa dtrv_va
to the start of the text segment and the base address of that segment
respectively.
.Pp
To calculate the relative offset of
.Fa dtrv_va
in the DSO the following calculation can be used:
.Pp
.Dl iOffset = dtrv_va - dtrv_start + dtrv_offset
.Pp
The segment can be found by walking the ELF program headers and looking
for the mapping where iOffset is included in the range
[GElf_Phdr.p_offset, GElf_Phdr.p_offset + GElf_Phdr.p_filesz)
.Pp
Using the
.Vt GElf_Phdr.p_vaddr
the base address of the segment can be calculated by
.Dl lbase = dtrv_start - GElf_Phdr.p_vaddr
.Pp
For symbol lookups the offset can now be calculated as
.Dl symOffset = dtrv_va - lbase
.El
.Sh FILES
.Bl -tag -width /dev/dt -compact
.It Pa /dev/dt
dynamic tracing device.
.El
.Sh ERRORS
An open of
.Pa /dev/dt
will fail if:
.Bl -tag -width Er
.It Bq Er EPERM
the
.Va kern.allowdt
.Xr sysctl 2
variable wasn't set.
.It Bq Er ENOMEM
not enough memory space was available.
.El
.Sh SEE ALSO
.Xr ioctl 2 ,
.Xr bt 5 ,
.Xr btrace 8
.Sh HISTORY
The
.Nm
dynamic tracing mechanism first appeared in
.Ox 6.7 .
|
