summaryrefslogtreecommitdiffstats
path: root/src/vnet/span/span.api
blob: a0f29153d271047e7bc241cbd763c29ad6a8ecb6 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
/* Hey Emacs use -*- mode: C -*- */
/*
 * Copyright (c) 2016 Cisco and/or its affiliates.
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at:
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

vl_api_version 1.0.0

 /** \brief Enable/Disable span to mirror traffic from one interface to another
    @param client_index - opaque cookie to identify the sender
    @param context - sender context which was passed in the request
    @param sw_if_index_from - interface to be mirorred
    @param sw_if_index_to - interface where the traffic is mirrored
    @param state - 0 = disabled, 1 = rx enabled, 2 = tx enabled, 3 tx & rx enabled
    @param is_l2 - 0 = mirror at hw device level, 1 = mirror at L2
*/
autoreply define sw_interface_span_enable_disable {
    u32 client_index;
    u32 context;
    u32 sw_if_index_from;
    u32 sw_if_index_to;
    u8  state;
    u8  is_l2;
};

/** \brief SPAN dump request
    @param client_index - opaque cookie to identify the sender
    @param context - sender context, to match reply w/ request
    @param is_l2 - 0 = hw device level, 1 = L2
*/
define sw_interface_span_dump {
    u32 client_index;
    u32 context;
    u8 is_l2;
};

/** \brief Reply to SPAN dump request
    @param context - sender context which was passed in the request
    @param sw_if_index_from - mirorred interface
    @param sw_if_index_to - interface where the traffic is mirrored
    @param state - 0 = disabled, 1 = rx enabled, 2 = tx enabled, 3 tx & rx enabled
*/
define sw_interface_span_details {
    u32 context;
    u32 sw_if_index_from;
    u32 sw_if_index_to;
    u8 state;
};
vm { color: #336699 } /* Name.Variable.Magic */ .highlight .il { color: #0000DD; font-weight: bold } /* Literal.Number.Integer.Long */ }
Multi-Architecture Graph Node Cookbook
======================================

In the context of graph node dispatch functions, it's easy enough to
use the vpp multi-architecture support setup. The point of the scheme
is simple: for performance-critical nodes, generate multiple CPU
hardware-dependent versions of the node dispatch functions, and pick
the best one at runtime.

The vpp scheme is simple enough to use, but details matter.

100,000 foot view
-----------------

We compile entire graph node dispatch function implementation files
multiple times. These compilations give rise to multiple versions of
the graph node dispatch functions. Per-node constructor-functions
interrogate CPU hardware, select the node dispatch function variant to
use, and set the vlib_node_registration_t ".function" member to the
address of the selected variant.

Details
-------

Declare the node dispatch function as shown, using the VLIB\_NODE\_FN macro. The
name of the node function **MUST** match the name of the graph node. 

:: 

    VLIB_NODE_FN (ip4_sdp_node) (vlib_main_t * vm, vlib_node_runtime_t * node,
                                 vlib_frame_t * frame)
    {
      if (PREDICT_FALSE (node->flags & VLIB_NODE_FLAG_TRACE))
        return ip46_sdp_inline (vm, node, frame, 1 /* is_ip4 */ ,
    			    1 /* is_trace */ );
      else
        return ip46_sdp_inline (vm, node, frame, 1 /* is_ip4 */ ,
    			    0 /* is_trace */ );
    }   

We need to generate *precisely one copy* of the
vlib_node_registration_t, error strings, and packet trace decode function.

Simply bracket these items with "#ifndef CLIB_MARCH_VARIANT...#endif":

::

    #ifndef CLIB_MARCH_VARIANT
    static u8 *
    format_sdp_trace (u8 * s, va_list * args)
    {
       <snip>
    }
    #endif

    ...

    #ifndef CLIB_MARCH_VARIANT
    static char *sdp_error_strings[] = {
    #define _(sym,string) string,
      foreach_sdp_error
    #undef _
    };
    #endif

    ...

    #ifndef CLIB_MARCH_VARIANT
    VLIB_REGISTER_NODE (ip4_sdp_node) =
    {
      // DO NOT set the .function structure member.
      // The multiarch selection __attribute__((constructor)) function
      // takes care of it at runtime
      .name = "ip4-sdp",
      .vector_size = sizeof (u32),
      .format_trace = format_sdp_trace,
      .type = VLIB_NODE_TYPE_INTERNAL,

      .n_errors = ARRAY_LEN(sdp_error_strings),
      .error_strings = sdp_error_strings,

      .n_next_nodes = SDP_N_NEXT,

      /* edit / add dispositions here */
      .next_nodes =
      {
        [SDP_NEXT_DROP] = "ip4-drop",
      },
    };
    #endif

To belabor the point: *do not* set the ".function" member! That's the job of the multi-arch
selection \_\_attribute\_\_((constructor)) function

Always inline node dispatch functions
-------------------------------------

It's typical for a graph dispatch function to contain one or more
calls to an inline function. See above. If your node dispatch function
is structured that way, make *ABSOLUTELY CERTAIN* to use the
"always_inline" macro:

::

    always_inline uword
    ip46_sdp_inline (vlib_main_t * vm, vlib_node_runtime_t * node, 
                 vlib_frame_t * frame,
    		 int is_ip4, int is_trace)
    { ... }

Otherwise, the compiler is highly likely NOT to build multiple
versions of the guts of your dispatch function. 

It's fairly easy to spot this mistake in "perf top." If you see, for
example, a bunch of functions with names of the form
"xxx_node_fn_avx2" in the profile, *BUT* your brand-new node function
shows up with a name of the form "xxx_inline.isra.1", it's quite likely
that the inline was declared "static inline" instead of "always_inline".

Modify CMakeLists.txt
---------------------

If the component in question already lists "MULTIARCH_SOURCES", simply
add the indicated .c file to the list.  Otherwise, add as shown
below. Note that the added file "new_multiarch_node.c" should appear in
*both* SOURCES and MULTIARCH_SOURCES:

::

    add_vpp_plugin(myplugin
      SOURCES
      new_multiarch_node.c
      ...  

      MULTIARCH_SOURCES
      new_ multiarch_node.c
      ...
     )