1.\" $OpenBSD: dt.4,v 1.7 2020/12/02 07:00:42 anton Exp $ 2.\" 3.\" Copyright (c) 2019 Martin Pieuchot <mpi@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: December 2 2020 $ 18.Dt DT 4 19.Os 20.Sh NAME 21.Nm dt 22.Nd dynamic tracer 23.Sh SYNOPSIS 24.Cd "pseudo-device dt" 25.Sh DESCRIPTION 26System and application tracing can happen in the kernel. 27It has to be configured and enabled through the 28.Xr ioctl 2 29interface exposed by the pseudo-device 30.Pa /dev/dt . 31.Pp 32This device can only be opened when the 33.Va kern.allowdt 34.Xr sysctl 2 35variable is set. 36.Sh IOCTL INTERFACE 37The 38.Xr ioctl 2 39command codes below are defined in 40.In dev/dt/dtvar.h . 41.Bl -tag -width xxxxxx 42.It Dv DTIOCGPLIST Fa "struct dtioc_probe *dtpr" 43Get available probe entries. 44.Bd -literal 45struct dtioc_probe { 46 size_t dtpr_size; 47 struct dtioc_probe_info *dtpr_probes; 48}; 49.Ed 50.Pp 51If 52.Va dtpr_size 53is non-zero, as many probes as possible that can fit into this size 54will be copied into the supplied buffer. 55On exit, 56.Va dtpr_size 57is always set to the total size required to hold all probe entries 58(i.e., it is set to 59.Li sizeof(struct dtioc_probe_info) * dt_nprobes ) . 60.It Dv DTIOCGSTATS Fa "struct dtioc_stat *dtst" 61Get statistics for current recording. 62.Bd -literal 63struct dtioc_stat { 64 uint64_t dtst_readevt; 65 uint64_t dtst_dropevt; 66}; 67.Ed 68.It Dv DTIOCRECORD Fa "int on" 69Start or stop recording. 70.It Dv DTIOCPRBENABLE Fa "struct dtioc_req *dtrq" 71Enable the given probe for recording. 72.Bd -literal 73struct dtioc_req { 74 uint32_t dtrq_pbn; 75 struct dt_filter dtrq_filter; 76 uint32_t dtrq_rate; 77 uint64_t dtrq_evtflags; 78}; 79.Ed 80.El 81.Sh FILES 82.Bl -tag -width /dev/dt -compact 83.It Pa /dev/dt 84dynamic tracing device. 85.El 86.Sh ERRORS 87An open of 88.Pa /dev/dt 89will fail if: 90.Bl -tag -width Er 91.It Bq Er EPERM 92the 93.Va kern.allowdt 94.Xr sysctl 2 95variable wasn't set. 96.It Bq Er ENOMEM 97not enough memory space was available. 98.El 99.Sh SEE ALSO 100.Xr ioctl 2 , 101.Xr bt 5 , 102.Xr btrace 8 103.Sh HISTORY 104The 105.Nm 106dynamic tracing mechanism first appeared in 107.Ox 6.7 . 108