2 * Copyright (c) 2015 Cisco and/or its affiliates.
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at:
7 * http://www.apache.org/licenses/LICENSE-2.0
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
16 * trace.c: VLIB trace buffer.
18 * Copyright (c) 2008 Eliot Dresselhaus
20 * Permission is hereby granted, free of charge, to any person obtaining
21 * a copy of this software and associated documentation files (the
22 * "Software"), to deal in the Software without restriction, including
23 * without limitation the rights to use, copy, modify, merge, publish,
24 * distribute, sublicense, and/or sell copies of the Software, and to
25 * permit persons to whom the Software is furnished to do so, subject to
26 * the following conditions:
28 * The above copyright notice and this permission notice shall be
29 * included in all copies or substantial portions of the Software.
31 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
32 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
33 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
34 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
35 * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
36 * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
37 * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
40 #include <vlib/vlib.h>
41 #include <vlib/threads.h>
42 #include <vnet/classify/vnet_classify.h>
44 u8 *vnet_trace_placeholder;
46 /* Helper function for nodes which only trace buffer data. */
48 vlib_trace_frame_buffers_only (vlib_main_t * vm,
49 vlib_node_runtime_t * node,
52 uword next_buffer_stride,
53 uword n_buffer_data_bytes_in_trace)
63 vlib_buffer_t *b0, *b1;
66 /* Prefetch next iteration. */
67 vlib_prefetch_buffer_with_index (vm, from[2], LOAD);
68 vlib_prefetch_buffer_with_index (vm, from[3], LOAD);
73 b0 = vlib_get_buffer (vm, bi0);
74 b1 = vlib_get_buffer (vm, bi1);
76 if (b0->flags & VLIB_BUFFER_IS_TRACED)
78 t0 = vlib_add_trace (vm, node, b0, n_buffer_data_bytes_in_trace);
79 clib_memcpy_fast (t0, b0->data + b0->current_data,
80 n_buffer_data_bytes_in_trace);
82 if (b1->flags & VLIB_BUFFER_IS_TRACED)
84 t1 = vlib_add_trace (vm, node, b1, n_buffer_data_bytes_in_trace);
85 clib_memcpy_fast (t1, b1->data + b1->current_data,
86 n_buffer_data_bytes_in_trace);
100 b0 = vlib_get_buffer (vm, bi0);
102 if (b0->flags & VLIB_BUFFER_IS_TRACED)
104 t0 = vlib_add_trace (vm, node, b0, n_buffer_data_bytes_in_trace);
105 clib_memcpy_fast (t0, b0->data + b0->current_data,
106 n_buffer_data_bytes_in_trace);
113 /* Free up all trace buffer memory. */
115 clear_trace_buffer (void)
118 vlib_trace_main_t *tm;
122 tm = &this_vlib_main->trace_main;
124 tm->trace_enable = 0;
125 vec_free (tm->nodes);
130 tm = &this_vlib_main->trace_main;
132 for (i = 0; i < vec_len (tm->trace_buffer_pool); i++)
133 if (!pool_is_free_index (tm->trace_buffer_pool, i))
134 vec_free (tm->trace_buffer_pool[i]);
135 pool_free (tm->trace_buffer_pool);
140 format_vlib_trace (u8 * s, va_list * va)
142 vlib_main_t *vm = va_arg (*va, vlib_main_t *);
143 vlib_trace_header_t *h = va_arg (*va, vlib_trace_header_t *);
144 vlib_trace_header_t *e = vec_end (h);
145 vlib_node_t *node, *prev_node;
146 clib_time_t *ct = &vm->clib_time;
152 node = vlib_get_node (vm, h->node_index);
154 if (node != prev_node)
157 (h->time - vm->cpu_time_main_loop_start) * ct->seconds_per_clock;
159 format (s, "\n%U: %v", format_time_interval, "h:m:s:u", t,
164 if (node->format_trace)
165 s = format (s, "\n %U", node->format_trace, vm, node, h->data);
167 s = format (s, "\n %U", node->format_buffer, h->data);
169 h = vlib_trace_header_next (h);
175 /* Root of all trace cli commands. */
177 VLIB_CLI_COMMAND (trace_cli_command,static) = {
179 .short_help = "Packet tracer commands",
184 trace_time_cmp (void *a1, void *a2)
186 vlib_trace_header_t **t1 = a1;
187 vlib_trace_header_t **t2 = a2;
188 i64 dt = t1[0]->time - t2[0]->time;
189 return dt < 0 ? -1 : (dt > 0 ? +1 : 0);
193 * Return 1 if this packet passes the trace filter, or 0 otherwise
196 filter_accept (vlib_trace_main_t * tm, vlib_trace_header_t * h)
198 vlib_trace_header_t *e = vec_end (h);
200 if (tm->filter_flag == 0)
204 * When capturing a post-mortem dispatch trace,
205 * toss all existing traces once per dispatch cycle.
206 * So we can trace 4 billion pkts without running out of
209 if (tm->filter_flag == FILTER_FLAG_POST_MORTEM)
212 if (tm->filter_flag == FILTER_FLAG_INCLUDE)
216 if (h->node_index == tm->filter_node_index)
218 h = vlib_trace_header_next (h);
222 else /* FILTER_FLAG_EXCLUDE */
226 if (h->node_index == tm->filter_node_index)
228 h = vlib_trace_header_next (h);
237 * Remove traces from the trace buffer pool that don't pass the filter
240 trace_apply_filter (vlib_main_t * vm)
242 vlib_trace_main_t *tm = &vm->trace_main;
243 vlib_trace_header_t **h;
244 vlib_trace_header_t ***traces_to_remove = 0;
251 if (tm->filter_flag == FILTER_FLAG_NONE)
255 * Ideally we would retain the first N traces that pass the filter instead
260 pool_foreach (h, tm->trace_buffer_pool)
262 accept = filter_accept(tm, h[0]);
264 if ((n_accepted == tm->filter_count) || !accept)
265 vec_add1 (traces_to_remove, h);
271 /* remove all traces that we don't want to keep */
272 for (index = 0; index < vec_len (traces_to_remove); index++)
274 trace_index = traces_to_remove[index] - tm->trace_buffer_pool;
275 vec_set_len (tm->trace_buffer_pool[trace_index], 0);
276 pool_put_index (tm->trace_buffer_pool, trace_index);
279 vec_free (traces_to_remove);
282 static clib_error_t *
283 cli_show_trace_buffer (vlib_main_t * vm,
284 unformat_input_t * input, vlib_cli_command_t * cmd)
286 vlib_trace_main_t *tm;
287 vlib_trace_header_t **h, **traces;
294 * By default display only this many traces. To display more, explicitly
295 * specify a max. This prevents unexpectedly huge outputs.
298 while (unformat_check_input (input) != (uword) UNFORMAT_END_OF_INPUT)
300 if (unformat (input, "max %d", &max))
303 return clib_error_create ("expected 'max COUNT', got `%U'",
304 format_unformat_error, input);
308 /* Get active traces from pool. */
312 fmt = "------------------- Start of thread %d %s -------------------\n";
313 s = format (s, fmt, index, vlib_worker_threads[index].name);
315 tm = &this_vlib_main->trace_main;
317 trace_apply_filter (this_vlib_main);
320 pool_foreach (h, tm->trace_buffer_pool)
322 vec_add1 (traces, h[0]);
325 if (vec_len (traces) == 0)
327 s = format (s, "No packets in trace buffer\n");
331 /* Sort them by increasing time. */
332 vec_sort_with_function (traces, trace_time_cmp);
334 for (i = 0; i < vec_len (traces); i++)
338 char *warn = "Limiting display to %d packets."
339 " To display more specify max.";
340 vlib_cli_output (vm, warn, max);
341 s = format (s, warn, max);
345 s = format (s, "Packet %d\n%U\n\n", i + 1, format_vlib_trace, vm,
355 vlib_cli_output (vm, "%v", s);
361 VLIB_CLI_COMMAND (show_trace_cli,static) = {
362 .path = "show trace",
363 .short_help = "Show trace buffer [max COUNT]",
364 .function = cli_show_trace_buffer,
368 int vlib_enable_disable_pkt_trace_filter (int enable) __attribute__ ((weak));
371 vlib_enable_disable_pkt_trace_filter (int enable)
377 vlib_trace_stop_and_clear (void)
379 vlib_enable_disable_pkt_trace_filter (0); /* disble tracing */
380 clear_trace_buffer ();
385 trace_update_capture_options (u32 add, u32 node_index, u32 filter, u8 verbose)
387 vlib_trace_main_t *tm;
388 vlib_trace_node_t *tn;
395 tm = &this_vlib_main->trace_main;
396 tm->verbose = verbose;
397 vec_validate (tm->nodes, node_index);
398 tn = tm->nodes + node_index;
401 * Adding 0 makes no real sense, and there wa no other way
402 * to explicilty zero-out the limits and count, so make
403 * an "add 0" request really be "set to 0".
406 tn->limit = tn->count = 0;
413 tm = &this_vlib_main->trace_main;
414 tm->trace_enable = 1;
417 vlib_enable_disable_pkt_trace_filter (! !filter);
420 static clib_error_t *
421 cli_add_trace_buffer (vlib_main_t * vm,
422 unformat_input_t * input, vlib_cli_command_t * cmd)
424 unformat_input_t _line_input, *line_input = &_line_input;
429 clib_error_t *error = 0;
431 if (!unformat_user (input, unformat_line_input, line_input))
434 if (vnet_trace_placeholder == 0)
435 vec_validate_aligned (vnet_trace_placeholder, 2048,
436 CLIB_CACHE_LINE_BYTES);
438 while (unformat_check_input (line_input) != (uword) UNFORMAT_END_OF_INPUT)
440 if (unformat (line_input, "%U %d",
441 unformat_vlib_node, vm, &node_index, &add))
443 else if (unformat (line_input, "verbose"))
445 else if (unformat (line_input, "filter"))
449 error = clib_error_create ("expected NODE COUNT, got `%U'",
450 format_unformat_error, line_input);
455 node = vlib_get_node (vm, node_index);
457 if ((node->flags & VLIB_NODE_FLAG_TRACE_SUPPORTED) == 0)
459 error = clib_error_create ("node '%U' doesn't support per-node "
460 "tracing. There may be another way to "
461 "initiate trace on this node.",
462 format_vlib_node_name, vm, node_index);
466 u32 filter_table = classify_get_trace_chain ();
467 if (filter && filter_table == ~0)
469 error = clib_error_create ("No packet trace filter configured...");
473 trace_update_capture_options (add, node_index, filter, verbose);
476 unformat_free (line_input);
482 VLIB_CLI_COMMAND (add_trace_cli,static) = {
484 .short_help = "trace add <input-graph-node> <add'l-pkts-for-node-> [filter] [verbose]",
485 .function = cli_add_trace_buffer,
490 * Configure a filter for packet traces.
492 * This supplements the packet trace feature so that only packets matching
493 * the filter are included in the trace. Currently the only filter is to
494 * keep packets that include a certain node in the trace or exclude a certain
497 * The count of traced packets in the "trace add" command is still used to
498 * create a certain number of traces. The "trace filter" command specifies
499 * how many of those packets should be retained in the trace.
501 * For example, 1Mpps of traffic is arriving and one of those packets is being
502 * dropped. To capture the trace for only that dropped packet, you can do:
503 * trace filter include error-drop 1
504 * trace add dpdk-input 1000000
508 * Note that the filter could be implemented by capturing all traces and just
509 * reducing traces displayed by the "show trace" function. But that would
510 * require a lot of memory for storing the traces, making that infeasible.
512 * To remove traces from the trace pool that do not include a certain node
513 * requires that the trace be "complete" before applying the filter. To
514 * accomplish this, the trace pool is filtered upon each iteraction of the
515 * main vlib loop. Doing so keeps the number of allocated traces down to a
516 * reasonably low number. This requires that tracing for a buffer is not
517 * performed after the vlib main loop interation completes. i.e. you can't
518 * save away a buffer temporarily then inject it back into the graph and
519 * expect that the trace_index is still valid (such as a traffic manager might
520 * do). A new trace buffer should be allocated for those types of packets.
522 * The filter can be extended to support multiple nodes and other match
523 * criteria (e.g. input sw_if_index, mac address) but for now just checks if
524 * a specified node is in the trace or not in the trace.
528 trace_filter_set (u32 node_index, u32 flag, u32 count)
532 vlib_trace_main_t *tm;
534 tm = &this_vlib_main->trace_main;
535 tm->filter_node_index = node_index;
536 tm->filter_flag = flag;
537 tm->filter_count = count;
540 * Clear the trace limits to stop any in-progress tracing
541 * Prevents runaway trace allocations when the filter changes
544 vec_free (tm->nodes);
549 static clib_error_t *
550 cli_filter_trace (vlib_main_t * vm,
551 unformat_input_t * input, vlib_cli_command_t * cmd)
553 u32 filter_node_index;
557 if (unformat (input, "include %U %d",
558 unformat_vlib_node, vm, &filter_node_index, &filter_count))
560 filter_flag = FILTER_FLAG_INCLUDE;
562 else if (unformat (input, "exclude %U %d",
563 unformat_vlib_node, vm, &filter_node_index,
566 filter_flag = FILTER_FLAG_EXCLUDE;
568 else if (unformat (input, "none"))
570 filter_flag = FILTER_FLAG_NONE;
571 filter_node_index = 0;
577 ("expected 'include NODE COUNT' or 'exclude NODE COUNT' or 'none', got `%U'",
578 format_unformat_error, input);
580 trace_filter_set (filter_node_index, filter_flag, filter_count);
586 VLIB_CLI_COMMAND (filter_trace_cli,static) = {
587 .path = "trace filter",
588 .short_help = "trace filter none | [include|exclude] NODE COUNT",
589 .function = cli_filter_trace,
593 static clib_error_t *
594 cli_clear_trace_buffer (vlib_main_t * vm,
595 unformat_input_t * input, vlib_cli_command_t * cmd)
597 vlib_trace_stop_and_clear ();
602 VLIB_CLI_COMMAND (clear_trace_cli,static) = {
603 .path = "clear trace",
604 .short_help = "Clear trace buffer and free memory",
605 .function = cli_clear_trace_buffer,
609 /* Placeholder function to get us linked in. */
611 vlib_trace_cli_reference (void)
616 vlib_add_trace (vlib_main_t * vm,
617 vlib_node_runtime_t * r, vlib_buffer_t * b, u32 n_data_bytes)
619 return vlib_add_trace_inline (vm, r, b, n_data_bytes);
622 vlib_is_packet_traced_fn_t *
623 vlib_is_packet_traced_function_from_name (const char *name)
625 vlib_trace_filter_function_registration_t *reg =
626 vlib_trace_filter_main.trace_filter_registration;
629 if (clib_strcmp (reg->name, name) == 0)
635 return reg->function;
638 vlib_is_packet_traced_fn_t *
639 vlib_is_packet_traced_default_function ()
641 vlib_trace_filter_function_registration_t *reg =
642 vlib_trace_filter_main.trace_filter_registration;
643 vlib_trace_filter_function_registration_t *tmp_reg = reg;
646 if (reg->priority > tmp_reg->priority)
650 return tmp_reg->function;
653 static clib_error_t *
654 vlib_trace_filter_function_init (vlib_main_t *vm)
656 vlib_is_packet_traced_fn_t *default_fn =
657 vlib_is_packet_traced_default_function ();
660 vlib_trace_main_t *tm = &this_vlib_main->trace_main;
661 tm->current_trace_filter_function = default_fn;
666 vlib_trace_filter_main_t vlib_trace_filter_main;
668 VLIB_INIT_FUNCTION (vlib_trace_filter_function_init);
670 static clib_error_t *
671 show_trace_filter_function (vlib_main_t *vm, unformat_input_t *input,
672 vlib_cli_command_t *cmd)
674 vlib_trace_filter_main_t *tfm = &vlib_trace_filter_main;
675 vlib_trace_main_t *tm = &vm->trace_main;
676 vlib_is_packet_traced_fn_t *current_trace_filter_fn =
677 tm->current_trace_filter_function;
678 vlib_trace_filter_function_registration_t *reg =
679 tfm->trace_filter_registration;
683 vlib_cli_output (vm, "%sname:%s description: %s priority: %u",
684 reg->function == current_trace_filter_fn ? "(*) " : "",
685 reg->name, reg->description, reg->priority);
691 VLIB_CLI_COMMAND (show_trace_filter_function_cli, static) = {
692 .path = "show trace filter function",
693 .short_help = "show trace filter function",
694 .function = show_trace_filter_function,
698 unformat_vlib_trace_filter_function (unformat_input_t *input, va_list *args)
700 vlib_is_packet_traced_fn_t **res =
701 va_arg (*args, vlib_is_packet_traced_fn_t **);
702 vlib_trace_filter_main_t *tfm = &vlib_trace_filter_main;
704 vlib_trace_filter_function_registration_t *reg =
705 tfm->trace_filter_registration;
708 if (unformat (input, reg->name))
710 *res = reg->function;
719 vlib_set_trace_filter_function (vlib_is_packet_traced_fn_t *x)
723 this_vlib_main->trace_main.current_trace_filter_function = x;
727 static clib_error_t *
728 set_trace_filter_function (vlib_main_t *vm, unformat_input_t *input,
729 vlib_cli_command_t *cmd)
731 unformat_input_t _line_input, *line_input = &_line_input;
732 vlib_is_packet_traced_fn_t *res = 0;
733 clib_error_t *error = 0;
735 if (!unformat_user (input, unformat_line_input, line_input))
738 while (unformat_check_input (line_input) != (uword) UNFORMAT_END_OF_INPUT)
740 if (unformat (line_input, "%U", unformat_vlib_trace_filter_function,
745 error = clib_error_create (
746 "expected valid trace filter function, got `%U'",
747 format_unformat_error, line_input);
751 vlib_set_trace_filter_function (res);
754 unformat_free (line_input);
759 VLIB_CLI_COMMAND (set_trace_filter_function_cli, static) = {
760 .path = "set trace filter function",
761 .short_help = "set trace filter function <func_name>",
762 .function = set_trace_filter_function,
765 * fd.io coding-style-patch-verification: ON
768 * eval: (c-set-style "gnu")