Branch data     Line data    Source code

       1                 :            : /* SPDX-License-Identifier: BSD-3-Clause
       2                 :            :  * Copyright(C) 2025 Marvell International Ltd.
       3                 :            :  */
       4                 :            : 
       5                 :            : #ifndef _RTE_GRAPH_MBUF_DYNFIELD_H_
       6                 :            : #define _RTE_GRAPH_MBUF_DYNFIELD_H_
       7                 :            : 
       8                 :            : #include <rte_common.h>
       9                 :            : #include <rte_mbuf.h>
      10                 :            : #include <rte_mbuf_dyn.h>
      11                 :            : 
      12                 :            : /**
      13                 :            :  * @file: rte_node_mbuf_dynfield.h
      14                 :            :  *
      15                 :            :  * @warning
      16                 :            :  * @b EXPERIMENTAL: this API may change without prior notice.
      17                 :            :  *
      18                 :            :  * Defines rte_node specific mbuf dynamic field region [rte_node_mbuf_dynfield_t]
      19                 :            :  * which can be used by both DPDK built-in and out-of-tree nodes
      20                 :            :  * for storing per-mbuf fields for graph walk.
      21                 :            :  */
      22                 :            : 
      23                 :            : #ifdef __cplusplus
      24                 :            : extern "C" {
      25                 :            : #endif
      26                 :            : 
      27                 :            : #ifndef RTE_NODE_MBUF_PERSISTENT_FIELDS_SIZE
      28                 :            : /** Size of persistent mbuf fields */
      29                 :            : #define RTE_NODE_MBUF_PERSISTENT_FIELDS_SIZE          (0)
      30                 :            : #endif /* !RTE_NODE_MBUF_PERSISTENT_FIELDS_SIZE */
      31                 :            : 
      32                 :            : #ifndef RTE_NODE_MBUF_OVERLOADABLE_FIELDS_SIZE
      33                 :            : /** Size of overloadable mbuf fields */
      34                 :            : #define RTE_NODE_MBUF_OVERLOADABLE_FIELDS_SIZE        (8)
      35                 :            : #endif /* !RTE_NODE_MBUF_OVERLOADABLE_FIELDS_SIZE */
      36                 :            : 
      37                 :            : /** Size of node mbuf dynamic field */
      38                 :            : #define RTE_NODE_MBUF_DYNFIELD_SIZE     \
      39                 :            :         (RTE_NODE_MBUF_PERSISTENT_FIELDS_SIZE + RTE_NODE_MBUF_OVERLOADABLE_FIELDS_SIZE)
      40                 :            : 
      41                 :            : /**
      42                 :            :  * Node mbuf overloadable data.
      43                 :            :  *
      44                 :            :  * Out-of-tree nodes can repurpose overloadable fields via
      45                 :            :  * rte_node_mbuf_overload_fields_get(mbuf). Overloadable fields are not
      46                 :            :  * preserved and typically can be used with-in two adjacent nodes in the graph.
      47                 :            :  */
      48                 :            : typedef struct rte_node_mbuf_overload_fields {
      49                 :            :         union {
      50                 :            :                 /* Following fields used by ip[4|6]-lookup -> ip[4|6]-rewrite nodes */
      51                 :            :                 union {
      52                 :            :                         struct {
      53                 :            :                                 uint16_t nh;
      54                 :            :                                 uint16_t ttl;
      55                 :            :                                 uint32_t cksum;
      56                 :            :                         };
      57                 :            :                         uint64_t u;
      58                 :            :                 };
      59                 :            :                 uint8_t data[RTE_NODE_MBUF_OVERLOADABLE_FIELDS_SIZE];
      60                 :            :         };
      61                 :            : } rte_node_mbuf_overload_fields_t;
      62                 :            : 
      63                 :            : /**
      64                 :            :  * rte_node specific mbuf dynamic field structure [rte_node_mbuf_dynfield_t]
      65                 :            :  *
      66                 :            :  * It holds two types of fields:
      67                 :            :  * 1. Persistent fields: Fields which are preserved across nodes during graph walk.
      68                 :            :  *    - Eg: rx/tx interface etc
      69                 :            :  * 2. Overloadable fields: Fields which can be repurposed by two adjacent nodes.
      70                 :            :  */
      71                 :            : typedef struct rte_node_mbuf_dynfield {
      72                 :            :         /**
      73                 :            :          * Persistent mbuf region across nodes in graph walk
      74                 :            :          *
      75                 :            :          * These fields are preserved across graph walk and can be accessed by
      76                 :            :          * rte_node_mbuf_dynfield_get() in fast path.
      77                 :            :          */
      78                 :            :         union {
      79                 :            :                 uint8_t persistent_data[RTE_NODE_MBUF_PERSISTENT_FIELDS_SIZE];
      80                 :            :         };
      81                 :            :         /**
      82                 :            :          * Overloadable mbuf fields across graph walk. Fields which can change.
      83                 :            :          *
      84                 :            :          * Two adjacent nodes (producer, consumer) can use this memory region for
      85                 :            :          * sharing per-mbuf specific information. Once mbuf leaves a consumer node,
      86                 :            :          * this region can be repurposed by another sets of [producer, consumer] node.
      87                 :            :          *
      88                 :            :          * In fast path, this region can be accessed by rte_node_mbuf_overload_fields_get().
      89                 :            :          */
      90                 :            :         rte_node_mbuf_overload_fields_t overloadable_data;
      91                 :            : } rte_node_mbuf_dynfield_t;
      92                 :            : 
      93                 :            : /**
      94                 :            :  * For a given mbuf and dynamic offset, return pointer to rte_node_mbuf_dynfield_t *
      95                 :            :  *
      96                 :            :  * @param m
      97                 :            :  *   Mbuf
      98                 :            :  * @param offset
      99                 :            :  *   Dynamic offset returned by @ref rte_node_mbuf_dynfield_register()
     100                 :            :  * @return
     101                 :            :  *  Pointer to node specific mbuf dynamic field structure
     102                 :            :  */
     103                 :            : __rte_experimental
     104                 :            : static __rte_always_inline rte_node_mbuf_dynfield_t *
     105                 :            : rte_node_mbuf_dynfield_get(struct rte_mbuf *m, const int offset)
     106                 :            : {
     107                 :            :         return RTE_MBUF_DYNFIELD(m, offset, struct rte_node_mbuf_dynfield *);
     108                 :            : }
     109                 :            : 
     110                 :            : /**
     111                 :            :  * For a given mbuf and dynamic offset, return pointer to overloadable fields.
     112                 :            :  * Nodes can typecast returned pointer to reuse for their own purpose.
     113                 :            :  *
     114                 :            :  * @param m
     115                 :            :  *   Mbuf
     116                 :            :  * @param offset
     117                 :            :  *   Dynamic offset returned by @ref rte_node_mbuf_dynfield_register()
     118                 :            :  * @return
     119                 :            :  * Pointer to node mbuf overloadable fields
     120                 :            :  */
     121                 :            : __rte_experimental
     122                 :            : static __rte_always_inline rte_node_mbuf_overload_fields_t *
     123                 :            : rte_node_mbuf_overload_fields_get(struct rte_mbuf *m, const int offset)
     124                 :            : {
     125                 :            :         rte_node_mbuf_dynfield_t *f = NULL;
     126                 :            : 
     127   [ #  #  #  #  :          0 :         f = RTE_MBUF_DYNFIELD(m, offset, rte_node_mbuf_dynfield_t *);
          #  #  #  #  #  
                #  #  # ]
     128                 :            : 
     129                 :            :         return &(f->overloadable_data);
     130                 :            : }
     131                 :            : 
     132                 :            : /**
     133                 :            :  *  Register rte_node specific common mbuf dynamic field region. Can be called
     134                 :            :  *  in rte_node_register()->init() function to save offset in node->ctx
     135                 :            :  *
     136                 :            :  *  In process() function, node->ctx can be passed to
     137                 :            :  *  - rte_node_mbuf_dynfield_get(mbuf, offset)
     138                 :            :  *  - rte_node_mbuf_overload_fields_get(mbuf, offset)
     139                 :            :  *
     140                 :            :  *  Can be called multiple times by any number of nodes in init() function.
     141                 :            :  *  - Very first call registers dynamic field and returns offset.
     142                 :            :  *  - Subsequent calls return same offset.
     143                 :            :  *
     144                 :            :  *  @return
     145                 :            :  *   <0 on error: rte_errno set to one of:
     146                 :            :  *    - ENOMEM - no memory
     147                 :            :  *   >=0 on success: dynamic field offset
     148                 :            :  */
     149                 :            : __rte_experimental
     150                 :            : int rte_node_mbuf_dynfield_register(void);
     151                 :            : 
     152                 :            : #ifdef __cplusplus
     153                 :            : }
     154                 :            : #endif
     155                 :            : 
     156                 :            : #endif /* _RTE_GRAPH_MBUF_DYNFIELD_H_ */