src/plugins/tracedump/tracedump.api

   1 /* Hey Emacs use -*- mode: C -*- */
   2 /*
   3  * tracedump.api - streaming packet trace dump API
   4  *
   5  * Copyright (c) 2020 Cisco and/or its affiliates
   6  * Licensed under the Apache License, Version 2.0 (the "License");
   7  * you may not use this file except in compliance with the License.
   8  * You may obtain a copy of the License at:
   9  *
  10  *     http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  * Unless required by applicable law or agreed to in writing, software
  13  * distributed under the License is distributed on an "AS IS" BASIS,
  14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  * See the License for the specific language governing permissions and
  16  * limitations under the License.
  17  */
  18
  19 /**
  20  * @file tracedump.api
  21  * @brief VPP control-plane API messages.
  22  *
  23  * This file defines VPP control-plane binary API messages which are generally
  24  * called through a shared memory interface.
  25  */
  26
  27
  28 option version = "0.1.0";
  29
  30 enum trace_filter_flag : u32
  31 {
  32   TRACE_FF_NONE = 0,
  33   TRACE_FF_INCLUDE_NODE = 1,
  34   TRACE_FF_EXCLUDE_NODE = 2,
  35   TRACE_FF_INCLUDE_CLASSIFIER = 3,
  36   TRACE_FF_EXCLUDE_CLASSIFIER = 4,
  37 };
  38
  39
  40 /** \brief trace_set_filters
  41     @param client_index - opaque cookie to identify the sender
  42     @param context - sender context, to match reply w/ request
  43     @param flag - One of the trace_filter_flag values
  44     @param node_index = The node-index to include/exclude
  45     @param classifier_table_index = The include/exclude classifier table
  46     @param count = The number of packets to include/exclude
  47 */
  48 autoreply define trace_set_filters
  49 {
  50   u32 client_index;
  51   u32 context;
  52   vl_api_trace_filter_flag_t flag;      /* TRACE_FF_* */
  53   u32 count;
  54   u32 node_index [default = 0xffffffff];
  55   u32 classifier_table_index [default = 0xffffffff];
  56   option vat_help =   "trace_set_filters [none] | [(include_node|exclude_node) <node-index>] | [(include_classifier|exclude_classifier) <classifier-index>] [count <count>]";
  57 };
  58
  59
  60 /** \brief trace_capture_packets
  61     @param client_index - opaque cookie to identify the sender
  62     @param context - sender context, to match reply w/ request
  63     @param node_index - graph input node whose packets are captured
  64     @param max_packets - maximum number of packets to capture
  65     @param use_filter - if true, apply filters to select/reject packets
  66     @param verbose - if true, set verbose packet capture flag
  67     @param pre_capture_clear - if true, clear buffer before capture begins
  68 */
  69 autoreply define trace_capture_packets
  70 {
  71   u32 client_index;
  72   u32 context;
  73   u32 node_index;
  74   u32 max_packets;
  75   bool use_filter;
  76   bool verbose;
  77   bool pre_capture_clear;
  78   option vat_help = "trace_capture_packets [node_index <index>] [max <max>] [pre_capture_clear] [use_filter] [verbose]";
  79 };
  80
  81
  82 /** \brief trace_clear_capture
  83     @param client_index - opaque cookie to identify the sender
  84     @param context - sender context, to match reply w/ request
  85 */
  86 autoreply define trace_clear_capture
  87 {
  88   u32 client_index;
  89   u32 context;
  90   option vat_help = "trace_clear_capture";
  91 };
  92
  93
  94 service {
  95     rpc trace_dump returns trace_dump_reply
  96         stream trace_details;
  97 };
  98
  99 define trace_dump {
 100     /* Client identifier, set from api_main.my_client_index */
 101     u32 client_index;
 102
 103     /* Arbitrary context, so client can match reply to request */
 104     u32 context;
 105
 106     /* Dispose of any cached data before we begin */
 107     u8 clear_cache;
 108
 109     /* iterator positions, both ~0 to just clear the cache */
 110     u32 thread_id;
 111     u32 position;
 112
 113     /* Max number of replies per burst */
 114     u32 max_records;
 115
 116     option vat_help = "trace_dump [thread_id <tid>] [position <pos>] [max <max>]";
 117 };
 118
 119 define trace_dump_reply {
 120     u32 context;
 121     i32 retval;
 122     u32 last_thread_id;
 123     u32 last_position;
 124     u8 more_this_thread;
 125     u8 more_threads;
 126     u8 flush_only;
 127     u8 done;
 128 };
 129
 130 define trace_details {
 131     /* Client identifier, set from api_main.my_client_index */
 132     u32 client_index;
 133
 134     /* Arbitrary context, so client can match reply to request */
 135     u32 context;
 136
 137     /* Position in the cache of this record */
 138     u32 thread_id;
 139     u32 position;
 140
 141     /* More or not */
 142     u8 more_this_thread;
 143     u8 more_threads;
 144     /* Needed when set ends in the middle of a batch */
 145     u8 done;
 146
 147     u32 packet_number;
 148     string trace_data[];
 149 };