xref: /freebsd/share/man/man4/dtrace_sctp.4 (revision c66ec88fed842fbaad62c30d510644ceb7bd2d71)
1.\" Copyright (c) 2018 Devin Teske <dteske@FreeBSD.org>
2.\"
3.\" Redistribution and use in source and binary forms, with or without
4.\" modification, are permitted provided that the following conditions
5.\" are met:
6.\" 1. Redistributions of source code must retain the above copyright
7.\"    notice, this list of conditions and the following disclaimer.
8.\" 2. Redistributions in binary form must reproduce the above copyright
9.\"    notice, this list of conditions and the following disclaimer in the
10.\"    documentation and/or other materials provided with the distribution.
11.\"
12.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
13.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
14.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
15.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
16.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
17.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
18.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
19.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
20.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
21.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
22.\" SUCH DAMAGE.
23.\"
24.\" $FreeBSD$
25.\"
26.Dd August 22, 2018
27.Dt DTRACE_SCTP 4
28.Os
29.Sh NAME
30.Nm dtrace_sctp
31.Nd a DTrace provider for tracing events related to the
32.Xr sctp 4
33protocol
34.Sh SYNOPSIS
35.Fn sctp:cwnd::init uint32_t uint32_t uintptr_t int int
36.Fn sctp:cwnd::ack uint32_t uint32_t uintptr_t int int
37.Fn sctp:cwnd::rttvar uint64_t uint64_t uint64_t uint64_t uint64_t
38.Fn sctp:cwnd::rttstep uint64_t uint64_t uint64_t uint64_t uint64_t
39.Fn sctp:cwnd::fr uint32_t uint32_t uintptr_t int int
40.Fn sctp:cwnd::to uint32_t uint32_t uintptr_t int int
41.Fn sctp:cwnd::bl uint32_t uint32_t uintptr_t int int
42.Fn sctp:cwnd::ecn uint32_t uint32_t uintptr_t int int
43.Fn sctp:cwnd::pd uint32_t uint32_t uintptr_t int int
44.Fn sctp:rwnd:assoc:val uint32_t uint32_t int int
45.Fn sctp:flightsize:net:val uint32_t uint32_t uintptr_t int int
46.Fn sctp:flightsize:assoc:val uint32_t uint32_t int int
47.Fn sctp:::receive "pktinfo_t *" "csinfo_t *" "ipinfo_t *" "sctpsinfo_t *" \
48    "sctpinfo_t *"
49.Fn sctp:::send "pktinfo_t *" "csinfo_t *" "ipinfo_t *" "sctpsinfo_t *" \
50    "sctpinfo_t *"
51.Fn sctp:::state-change "void *" "csinfo_t *" "void *" "sctpsinfo_t *" \
52    "void *" "sctplsinfo_t *"
53.Sh DESCRIPTION
54The DTrace
55.Nm sctp
56provider allows users to trace events in the
57.Xr sctp 4
58protocol implementation.
59This provider is similar to the
60.Xr dtrace_ip 4
61and
62.Xr dtrace_udp 4
63providers,
64but additionally contains probes corresponding to protocol events at a level
65higher than packet reception and transmission.
66.Pp
67The
68.Fn sctp:cwnd::
69probes track changes in the congestion window on a netp.
70The
71.Fn sctp:rwnd::
72probes track changes in the receiver window for an assoc.
73The
74.Fn sctp:flightsize:net:val
75probe tracks changes in the flight size on a net or assoc and the
76.Fn sctp:flightsize:assoc:val
77probe provides the total flight version.
78.Pp
79The arguments of all
80.Nm sctp
81probes except for
82.Fn sctp:cwnd::rtt*
83and
84.Fn sctp::assoc:val
85are the Vtag for this end,
86the port number of the local side,
87the pointer to
88.Dv struct sctp_nets *changing ,
89the old value of the cwnd,
90and the new value of the cwnd.
91.Pp
92The arguments of
93.Fn sctp:::val
94are similar to the above except the fourth argument is the up/down amount.
95.Pp
96The
97.Fn sctp:cwnd::rtt*
98probe arguments are a bitmap of
99.Dv Vtag << 32 | localport << 16 | remoteport ,
100a bitmap of
101.Dv obw | nbw ,
102a bitmap of
103.Dv bwrtt | newrtt ,
104.Dv flight ,
105and a bitmap of
106.Dv (cwnd << 32) | point << 16 | retval(0/1) .
107.Pp
108The
109.Fn sctp:cwnd::init
110probe fires when a remotely-initiated active SCTP open succeeds.
111At this point the new connection is in the ESTABLISHED state, and the probe
112arguments expose the headers associated with the final ACK of the four-way
113handshake.
114.Pp
115The
116.Fn sctp:::send
117and
118.Fn sctp:::receive
119probes fire when the host sends or receives an SCTP packet, respectively.
120As with the
121.Xr dtrace_udp 4
122provider,
123.Nm sctp
124probes fire only for packets sent by or to the local host; forwarded packets are
125handled in the IP layer and are only visible to the
126.Xr dtrace_ip 4
127provider.
128.Pp
129The
130.Fn sctp:::state-change
131probe fires upon local SCTP association state transitions.
132Its first, third and fifth arguments are currently always
133.Dv NULL .
134Its last argument describes the from-state in the transition, and the to-state
135can be obtained from
136.Dv args[3]->sctps_state .
137.\" .Sh ARGUMENTS
138.Sh FILES
139.Bl -tag -width "/usr/lib/dtrace/sctp.d" -compact
140.It Pa /usr/lib/dtrace/sctp.d
141DTrace type and translator definitions for the
142.Nm sctp
143provider.
144.El
145.Sh EXAMPLES
146A script that logs SCTP packets in real time:
147.Bd -literal -offset indent
148#pragma D option quiet
149#pragma D option switchrate=10hz
150
151dtrace:::BEGIN
152{
153        printf(" %3s %15s:%-5s      %15s:%-5s\n", "CPU",
154            "LADDR", "LPORT", "RADDR", "RPORT");
155}
156
157sctp:::send
158{
159        printf(" %3d %16s:%-5d -> %16s:%-5d\n", cpu,
160            args[2]->ip_saddr, args[4]->sctp_sport,
161            args[2]->ip_daddr, args[4]->sctp_dport);
162}
163
164sctp:::receive
165{
166        printf(" %3d %16s:%-5d <- %16s:%-5d\n", cpu,
167            args[2]->ip_daddr, args[4]->sctp_dport,
168            args[2]->ip_saddr, args[4]->sctp_sport);
169}
170.Ed
171A script that logs SCTP association state changes as they occur:
172.Bd -literal -offset indent
173#pragma D option quiet
174#pragma D option switchrate=10
175
176int last[int];
177
178dtrace:::BEGIN
179{
180        printf(" %3s %12s  %-25s    %-25s\n",
181            "CPU", "DELTA(us)", "OLD", "NEW");
182}
183
184sctp:::state-change
185/ last[args[1]->cs_cid] /
186{
187        this->elapsed = (timestamp - last[args[1]->cs_cid]) / 1000;
188        printf(" %3d %12d  %-25s -> %-25s\n", cpu, this->elapsed,
189            sctp_state_string[args[5]->sctps_state],
190            sctp_state_string[args[3]->sctps_state]);
191        last[args[1]->cs_cid] = timestamp;
192}
193
194sctp:::state-change
195/ last[args[1]->cs_cid] == 0 /
196{
197        printf(" %3d %12s  %-25s -> %-25s\n", cpu, "-",
198            sctp_state_string[args[5]->sctps_state],
199            sctp_state_string[args[3]->sctps_state]);
200        last[args[1]->cs_cid] = timestamp;
201}
202.Ed
203.Sh COMPATIBILITY
204The
205.Fn sctp:::send ,
206.Fn sctp:::receive ,
207and
208.Fn sctp:::state-change
209probes are compatible with the
210.Nm sctp
211provider in Solaris.
212All other probes are only available in FreeBSD.
213.Sh SEE ALSO
214.Xr dtrace 1 ,
215.Xr dtrace_ip 4 ,
216.Xr dtrace_udp 4 ,
217.Xr dtrace_udplite 4 ,
218.Xr sctp 4 ,
219.Xr SDT 9
220.\" .Sh HISTORY
221.\" The
222.\" .Nm sctp
223.\" provider first appeared in
224.\" .Fx
225.\" UNKNOWN.
226.Sh AUTHORS
227This manual page was written by
228.An Devin Teske Aq Mt dteske@FreeBSD.org .
229