diff options
Diffstat (limited to 'static/openbsd/man4/dt.4')
| -rw-r--r-- | static/openbsd/man4/dt.4 | 158 |
1 files changed, 158 insertions, 0 deletions
diff --git a/static/openbsd/man4/dt.4 b/static/openbsd/man4/dt.4 new file mode 100644 index 00000000..26a22b8e --- /dev/null +++ b/static/openbsd/man4/dt.4 @@ -0,0 +1,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 . |