1 /*
2  * ngtcp2
3  *
4  * Copyright (c) 2019 ngtcp2 contributors
5  *
6  * Permission is hereby granted, free of charge, to any person obtaining
7  * a copy of this software and associated documentation files (the
8  * "Software"), to deal in the Software without restriction, including
9  * without limitation the rights to use, copy, modify, merge, publish,
10  * distribute, sublicense, and/or sell copies of the Software, and to
11  * permit persons to whom the Software is furnished to do so, subject to
12  * the following conditions:
13  *
14  * The above copyright notice and this permission notice shall be
15  * included in all copies or substantial portions of the Software.
16  *
17  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
18  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
19  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
20  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
21  * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
22  * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
23  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
24  */
25 #ifndef NGTCP2_QLOG_H
26 #define NGTCP2_QLOG_H
27 
28 #ifdef HAVE_CONFIG_H
29 #  include <config.h>
30 #endif /* HAVE_CONFIG_H */
31 
32 #include <ngtcp2/ngtcp2.h>
33 
34 #include "ngtcp2_pkt.h"
35 #include "ngtcp2_cc.h"
36 #include "ngtcp2_buf.h"
37 #include "ngtcp2_rtb.h"
38 
39 /* NGTCP2_QLOG_BUFLEN is the length of heap allocated buffer for
40    qlog. */
41 #define NGTCP2_QLOG_BUFLEN 4096
42 
43 typedef enum ngtcp2_qlog_side {
44   NGTCP2_QLOG_SIDE_LOCAL,
45   NGTCP2_QLOG_SIDE_REMOTE,
46 } ngtcp2_qlog_side;
47 
48 typedef struct ngtcp2_qlog {
49   /* write is a callback function to write qlog. */
50   ngtcp2_qlog_write write;
51   /* ts is the initial timestamp */
52   ngtcp2_tstamp ts;
53   /* last_ts is the timestamp observed last time. */
54   ngtcp2_tstamp last_ts;
55   /* buf is a heap allocated buffer to write exclusively
56      packet_received and packet_sent. */
57   ngtcp2_buf buf;
58   /* user_data is an opaque pointer which is passed to write
59      callback. */
60   void *user_data;
61 } ngtcp2_qlog;
62 
63 /*
64  * ngtcp2_qlog_init initializes |qlog|.
65  */
66 void ngtcp2_qlog_init(ngtcp2_qlog *qlog, ngtcp2_qlog_write write,
67                       ngtcp2_tstamp ts, void *user_data);
68 
69 /*
70  * ngtcp2_qlog_start writes qlog preamble.
71  */
72 void ngtcp2_qlog_start(ngtcp2_qlog *qlog, const ngtcp2_cid *odcid, int server);
73 
74 /*
75  * ngtcp2_qlog_end writes closing part of qlog.
76  */
77 void ngtcp2_qlog_end(ngtcp2_qlog *qlog);
78 
79 /*
80  * ngtcp2_qlog_write_frame writes |fr| to qlog->buf.
81  * ngtcp2_qlog_pkt_received_start or ngtcp2_qlog_pkt_sent_start must
82  * be called before calling this function.
83  */
84 void ngtcp2_qlog_write_frame(ngtcp2_qlog *qlog, const ngtcp2_frame *fr);
85 
86 /*
87  * ngtcp2_qlog_pkt_received_start starts to write packet_received
88  * event.  It initializes qlog->buf.  It writes qlog to qlog->buf.
89  * ngtcp2_qlog_pkt_received_end will flush the content of qlog->buf to
90  * write callback.
91  */
92 void ngtcp2_qlog_pkt_received_start(ngtcp2_qlog *qlog);
93 
94 /*
95  * ngtcp2_qlog_pkt_received_end ends packet_received event and sends
96  * the content of qlog->buf to qlog->write callback.
97  */
98 void ngtcp2_qlog_pkt_received_end(ngtcp2_qlog *qlog, const ngtcp2_pkt_hd *hd,
99                                   size_t pktlen);
100 
101 /*
102  * ngtcp2_qlog_pkt_sent_start starts to write packet_sent event.  It
103  * initializes qlog->buf.  It writes qlog to qlog->buf.
104  * ngtcp2_qlog_pkt_sent_end will flush the content of qlog->buf to
105  * write callback.
106  */
107 void ngtcp2_qlog_pkt_sent_start(ngtcp2_qlog *qlog);
108 
109 /*
110  * ngtcp2_qlog_pkt_sent_end ends packet_sent event and sends the
111  * content of qlog->buf to qlog->write callback.
112  */
113 void ngtcp2_qlog_pkt_sent_end(ngtcp2_qlog *qlog, const ngtcp2_pkt_hd *hd,
114                               size_t pktlen);
115 
116 /*
117  * ngtcp2_qlog_parameters_set_transport_params writes |params| to qlog
118  * as parameters_set event.  |server| is nonzero if the local endpoint
119  * is server.  If |local| is nonzero, it is "owner" field becomes
120  * "local", otherwise "remote".
121  */
122 void ngtcp2_qlog_parameters_set_transport_params(
123     ngtcp2_qlog *qlog, const ngtcp2_transport_params *params, int server,
124     ngtcp2_qlog_side side);
125 
126 /*
127  * ngtcp2_qlog_metrics_updated writes metrics_updated event of
128  * recovery category.
129  */
130 void ngtcp2_qlog_metrics_updated(ngtcp2_qlog *qlog,
131                                  const ngtcp2_conn_stat *cstat);
132 
133 /*
134  * ngtcp2_qlog_pkt_lost writes packet_lost event.
135  */
136 void ngtcp2_qlog_pkt_lost(ngtcp2_qlog *qlog, ngtcp2_rtb_entry *ent);
137 
138 /*
139  * ngtcp2_qlog_retry_pkt_received writes packet_received event for a
140  * received Retry packet.
141  */
142 void ngtcp2_qlog_retry_pkt_received(ngtcp2_qlog *qlog, const ngtcp2_pkt_hd *hd);
143 
144 #endif /* NGTCP2_QLOG_H */
145