diff options
Diffstat (limited to 'vlib')
| -rw-r--r-- | vlib/vlib/buffer_node.h | 47 | ||||
| -rw-r--r-- | vlib/vlib/node_funcs.h | 93 |
2 files changed, 139 insertions, 1 deletions
diff --git a/vlib/vlib/buffer_node.h b/vlib/vlib/buffer_node.h index 0fa5c8093ca..5985ccf500d 100644 --- a/vlib/vlib/buffer_node.h +++ b/vlib/vlib/buffer_node.h @@ -40,6 +40,33 @@ #ifndef included_vlib_buffer_node_h #define included_vlib_buffer_node_h +/** \file + vlib buffer/node functions +*/ + +/** \brief Finish enqueueing two buffers forward in the graph. + Standard dual loop boilerplate element. This is a MACRO, + with MULTIPLE SIDE EFFECTS. In the ideal case, + <code>next_index == next0 == next1</code>, + which means that the speculative enqueue at the top of the dual loop + has correctly dealt with both packets. In that case, the macro does + nothing at all. + + @param vm vlib_main_t pointer, varies by thread + @param node current node vlib_node_runtime_t pointer + @param next_index speculated next index used for both packets + @param to_next speculated vector pointer used for both packets + @param n_left_to_next number of slots left in speculated vector + @param bi0 first buffer index + @param bi1 second buffer index + @param next0 actual next index to be used for the first packet + @param next1 actual next index to be used for the second packet + + @return @c next_index -- speculative next index to be used for future packets + @return @c to_next -- speculative frame to be used for future packets + @return @c n_left_to_next -- number of slots left in speculative frame +*/ + #define vlib_validate_buffer_enqueue_x2(vm,node,next_index,to_next,n_left_to_next,bi0,bi1,next0,next1) \ do { \ int enqueue_code = (next0 != next_index) + 2*(next1 != next_index); \ @@ -80,6 +107,26 @@ do { \ } \ } while (0) +/** \brief Finish enqueueing one buffer forward in the graph. + Standard single loop boilerplate element. This is a MACRO, + with MULTIPLE SIDE EFFECTS. In the ideal case, + <code>next_index == next0</code>, + which means that the speculative enqueue at the top of the single loop + has correctly dealt with the packet in hand. In that case, the macro does + nothing at all. + + @param vm vlib_main_t pointer, varies by thread + @param node current node vlib_node_runtime_t pointer + @param next_index speculated next index used for both packets + @param to_next speculated vector pointer used for both packets + @param n_left_to_next number of slots left in speculated vector + @param bi0 first buffer index + @param next0 actual next index to be used for the first packet + + @return @c next_index -- speculative next index to be used for future packets + @return @c to_next -- speculative frame to be used for future packets + @return @c n_left_to_next -- number of slots left in speculative frame +*/ #define vlib_validate_buffer_enqueue_x1(vm,node,next_index,to_next,n_left_to_next,bi0,next0) \ do { \ if (PREDICT_FALSE (next0 != next_index)) \ diff --git a/vlib/vlib/node_funcs.h b/vlib/vlib/node_funcs.h index 18342e2661d..f567ce54909 100644 --- a/vlib/vlib/node_funcs.h +++ b/vlib/vlib/node_funcs.h @@ -37,15 +37,34 @@ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */ +/** \file + vlib node functions +*/ + + #ifndef included_vlib_node_funcs_h #define included_vlib_node_funcs_h #include <vppinfra/fifo.h> +/** \brief Get vlib node by index. + @warning This function will ASSERT if @c i is out of range. + @param vm vlib_main_t pointer, varies by thread + @param i node index. + @return pointer to the requested vlib_node_t. +*/ + always_inline vlib_node_t * vlib_get_node (vlib_main_t * vm, u32 i) { return vec_elt (vm->node_main.nodes, i); } +/** \brief Get vlib node by graph arc (next) index. + @param vm vlib_main_t pointer, varies by thread + @param node_index index of original node + @param next_index graph arc index + @return pointer to the vlib_node_t at the end of the indicated arc +*/ + always_inline vlib_node_t * vlib_get_next_node (vlib_main_t * vm, u32 node_index, u32 next_index) { @@ -57,6 +76,12 @@ vlib_get_next_node (vlib_main_t * vm, u32 node_index, u32 next_index) return vlib_get_node (vm, n->next_nodes[next_index]); } +/** \brief Get node runtime by node index. + @param vm vlib_main_t pointer, varies by thread + @param node_index index of node + @return pointer to the indicated vlib_node_runtime_t +*/ + always_inline vlib_node_runtime_t * vlib_node_get_runtime (vlib_main_t * vm, u32 node_index) { @@ -72,6 +97,12 @@ vlib_node_get_runtime (vlib_main_t * vm, u32 node_index) } } +/** \brief Get node runtime private data by node index. + @param vm vlib_main_t pointer, varies by thread + @param node_index index of the node + @return pointer to the indicated vlib_node_runtime_t private data +*/ + always_inline void * vlib_node_get_runtime_data (vlib_main_t * vm, u32 node_index) { @@ -79,6 +110,13 @@ vlib_node_get_runtime_data (vlib_main_t * vm, u32 node_index) return r->runtime_data; } +/** \brief Set node runtime private data. + @param vm vlib_main_t pointer, varies by thread + @param node_index index of the node + @param runtime_data arbitrary runtime private data + @param n_runtime_data_bytes size of runtime private data +*/ + always_inline void vlib_node_set_runtime_data (vlib_main_t * vm, u32 node_index, void * runtime_data, @@ -96,6 +134,11 @@ vlib_node_set_runtime_data (vlib_main_t * vm, u32 node_index, clib_memcpy (r->runtime_data, n->runtime_data, vec_len (n->runtime_data)); } +/** \brief Set node dispatch state. + @param vm vlib_main_t pointer, varies by thread + @param node_index index of the node + @param new_state new state for node, see vlib_node_state_t +*/ always_inline void vlib_node_set_state (vlib_main_t * vm, u32 node_index, vlib_node_state_t new_state) { @@ -198,13 +241,27 @@ vlib_frame_vector_byte_offset (u32 scalar_size) VLIB_FRAME_VECTOR_ALIGN); } +/** \brief Get pointer to frame vector data. + @param f vlib_frame_t pointer + @return pointer to first vector element in frame +*/ always_inline void * vlib_frame_vector_args (vlib_frame_t * f) { return (void *) f + vlib_frame_vector_byte_offset (f->scalar_size); } -/* Scalar data lies before aligned vector data. */ +/** \brief Get pointer to frame scalar data. + + @warning This is almost certainly not the function you wish to call. + See @ref vlib_frame_vector_args instead. + + @param f vlib_frame_t pointer + + @return arbitrary node scalar data + + @sa vlib_frame_vector_args +*/ always_inline void * vlib_frame_args (vlib_frame_t * f) { return vlib_frame_vector_args (f) - f->scalar_size; } @@ -232,6 +289,20 @@ vlib_node_runtime_get_next_frame (vlib_main_t * vm, return nf; } +/** \brief Get pointer to frame by (@c node_index, @c next_index). + + @warning This is not a function that you should call directly. + See @ref vlib_get_next_frame instead. + + @param vm vlib_main_t pointer, varies by thread + @param node_index index of the node + @param next_index graph arc index + + @return pointer to the requested vlib_next_frame_t + + @sa vlib_get_next_frame +*/ + always_inline vlib_next_frame_t * vlib_node_get_next_frame (vlib_main_t * vm, u32 node_index, @@ -262,6 +333,19 @@ do { \ (n_vectors_left) = VLIB_FRAME_SIZE - _n; \ } while (0) + +/** \brief Get pointer to next frame vector data by + (@c vlib_node_runtime_t, @c next_index). + Standard single/dual loop boilerplate element. + @attention This is a MACRO, with SIDE EFFECTS. + + @param vm vlib_main_t pointer, varies by thread + @param node current node vlib_node_runtime_t pointer + @param next_index requested graph arc index + + @return @c vectors -- pointer to next available vector slot + @return @c n_vectors_left -- number of vector slots available +*/ #define vlib_get_next_frame(vm,node,next_index,vectors,n_vectors_left) \ vlib_get_next_frame_macro (vm, node, next_index, \ vectors, n_vectors_left, \ @@ -272,6 +356,13 @@ do { \ vectors, n_vectors_left, \ /* alloc new frame */ 1) +/** \brief Release pointer to next frame vector data. + Standard single/dual loop boilerplate element. + @param vm vlib_main_t pointer, varies by thread + @param r current node vlib_node_runtime_t pointer + @param next_index graph arc index + @param n_packets_left number of slots still available in vector +*/ void vlib_put_next_frame (vlib_main_t * vm, vlib_node_runtime_t * r, |