1.\" Copyright (c) 2015 Mark Johnston <markj@FreeBSD.org> 2.\" Copyright (c) 2018 Michael Tuexen <tuexen@FreeBSD.org> 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.\" $FreeBSD$ 27.\" 28.Dd August 1, 2018 29.Dt DTRACE_UDPLITE 4 30.Os 31.Sh NAME 32.Nm dtrace_udplite 33.Nd a DTrace provider for tracing events related to the UDP-Lite protocol 34.Sh SYNOPSIS 35.Fn udplite:::receive "pktinfo_t *" "csinfo_t *" "ipinfo_t *" "udplitesinfo_t *" \ 36 "udpliteinfo_t *" 37.Fn udplite:::send "pktinfo_t *" "csinfo_t *" "ipinfo_t *" "udplitesinfo_t *" \ 38 "udpliteinfo_t *" 39.Sh DESCRIPTION 40The DTrace 41.Nm udplite 42provider allows users to trace events in the 43.Xr udplite 4 44protocol implementation. 45The 46.Fn udplite:::send 47probe fires whenever the kernel prepares to transmit a UDP-Lite packet, and the 48.Fn udplite:::receive 49probe fires whenever the kernel receives a UDP-Lite packet, unless 50the UDP-Lite header is incomplete, 51the destination port is 0, 52the length field is invalid, 53or the checksum is wrong. 54The arguments to these probes can be used to obtain detailed information about 55the IP and UDP-Lite headers of the corresponding packet. 56.Sh ARGUMENTS 57The 58.Vt pktinfo_t 59argument is currently unimplemented and is included for compatibility with other 60implementations of this provider. 61Its fields are: 62.Bl -tag -width "uintptr_t pkt_addr" -offset indent 63.It Vt uintptr_t pkt_addr 64Always set to 0. 65.El 66.Pp 67The 68.Vt csinfo_t 69argument is currently unimplemented and is included for compatibility with other 70implementations of this provider. 71Its fields are: 72.Bl -tag -width "uintptr_t cs_addr" -offset indent 73.It Vt uintptr_t cs_addr 74Always set to 0. 75.It Vt uint64_t cs_cid 76A pointer to the 77.Vt struct inpcb 78for this packet, or 79.Dv NULL . 80.It Vt pid_t cs_pid 81Always set to 0. 82.El 83.Pp 84The 85.Vt ipinfo_t 86argument contains IP fields common to both IPv4 and IPv6 packets. 87Its fields are: 88.Bl -tag -width "uint32_t ip_plength" -offset indent 89.It Vt uint8_t ip_ver 90IP version of the packet, 4 for IPv4 packets and 6 for IPv6 packets. 91.It Vt uint32_t ip_plength 92IP payload size. 93This does not include the size of the IP header or IPv6 option headers. 94.It Vt string ip_saddr 95IP source address. 96.It Vt string ip_daddr 97IP destination address. 98.El 99.Pp 100The 101.Vt udplitesinfo_t 102argument contains the state of the UDP-Lite connection associated with the packet. 103Its fields are: 104.Bl -tag -width "uintptr_t udplites_addr" -offset indent 105.It Vt uintptr_t udplites_addr 106Pointer to the 107.Vt struct inpcb 108containing the IP state for the associated socket. 109.It Vt uint16_t udplites_lport 110Local UDP-Lite port. 111.It Vt uint16_t udplites_rport 112Remote UDP-Lite port. 113.It Vt string udplites_laddr 114Local IPv4 or IPv6 address. 115.It Vt string udplites_raddr 116Remote IPv4 or IPv6 address. 117.El 118.Pp 119The 120.Vt udpliteinfo_t 121argument is the raw UDP-Lite header of the packet, with all fields in host order. 122Its fields are: 123.Bl -tag -width "struct udplitehdr *udplite_hdr" -offset indent 124.It Vt uint16_t udplite_sport 125Source UDP-Lite port. 126.It Vt uint16_t udplite_dport 127Destination UDP-Lite port. 128.It Vt uint16_t udplite_coverage 129Checksum coverage of the UDP-Lite header, in bytes, or 0 for full coverage. 130.It Vt uint16_t udplite_checksum 131A checksum of the UDP-Lite header and payload, or 0 if no checksum was calculated. 132.It Vt struct udplitehdr *udplite_hdr 133A pointer to the raw UDP-Lite header. 134.El 135.Sh FILES 136.Bl -tag -width "/usr/lib/dtrace/udplite.d" -compact 137.It Pa /usr/lib/dtrace/udplite.d 138DTrace type and translator definitions for the 139.Nm udplite 140provider. 141.El 142.Sh EXAMPLES 143The following script counts transmitted packets by destination port. 144.Bd -literal -offset indent 145udplite:::send 146{ 147 @num[args[4]->udplite_dport] = count(); 148} 149.Ed 150.Pp 151This script will print some details of each UDP-Lite packet as it is sent or received 152by the kernel: 153.Bd -literal -offset indent 154#pragma D option quiet 155#pragma D option switchrate=10Hz 156 157dtrace:::BEGIN 158{ 159 printf(" %10s %36s %-36s %6s\\n", "DELTA(us)", "SOURCE", 160 "DEST", "COV"); 161 last = timestamp; 162} 163 164udplite:::send 165{ 166 this->elapsed = (timestamp - last) / 1000; 167 self->dest = strjoin(strjoin(args[2]->ip_daddr, ":"), 168 lltostr(args[4]->udplite_dport)); 169 printf(" %10d %30s:%-5d -> %-36s %6d\\n", this->elapsed, 170 args[2]->ip_saddr, args[4]->udplite_sport, 171 self->dest, args[4]->udplite_coverage); 172 last = timestamp; 173} 174 175udplite:::receive 176{ 177 this->elapsed = (timestamp - last) / 1000; 178 self->dest = strjoin(strjoin(args[2]->ip_saddr, ":"), 179 lltostr(args[4]->udplite_sport)); 180 printf(" %10d %30s:%-5d <- %-36s %6d\\n", this->elapsed, 181 args[2]->ip_daddr, args[4]->udplite_dport, 182 self->dest, args[4]->udplite_coverage); 183 last = timestamp; 184} 185.Ed 186.Sh SEE ALSO 187.Xr dtrace 1 , 188.Xr dtrace_ip 4 , 189.Xr dtrace_sctp 4 , 190.Xr dtrace_tcp 4 , 191.Xr dtrace_udp 4 , 192.Xr udplite 4 , 193.Xr SDT 9 194.Sh HISTORY 195The 196.Nm udplite 197provider first appeared in 198.Fx 19912.0. 200.Sh AUTHORS 201This manual page was written by 202.An Mark Johnston Aq Mt markj@FreeBSD.org 203and 204.An Michael Tuexen Aq Mt tuexen@FreeBSD.org . 205