lib/librte_mbuf_offload/rte_mbuf_offload.h

   1 /*-
   2  *   BSD LICENSE
   3  *
   4  *   Copyright(c) 2015 Intel Corporation. All rights reserved.
   5  *
   6  *   Redistribution and use in source and binary forms, with or without
   7  *   modification, are permitted provided that the following conditions
   8  *   are met:
   9  *
  10  *     * Redistributions of source code must retain the above copyright
  11  *       notice, this list of conditions and the following disclaimer.
  12  *     * Redistributions in binary form must reproduce the above copyright
  13  *       notice, this list of conditions and the following disclaimer in
  14  *       the documentation and/or other materials provided with the
  15  *       distribution.
  16  *     * Neither the name of Intel Corporation nor the names of its
  17  *       contributors may be used to endorse or promote products derived
  18  *       from this software without specific prior written permission.
  19  *
  20  *   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  21  *   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  22  *   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  23  *   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  24  *   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  25  *   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  26  *   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  27  *   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  28  *   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  29  *   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  30  *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  31  */
  32
  33 #ifndef _RTE_MBUF_OFFLOAD_H_
  34 #define _RTE_MBUF_OFFLOAD_H_
  35
  36 /**
  37  * @file
  38  * RTE mbuf offload
  39  *
  40  * The rte_mbuf_offload library provides the ability to specify a device generic
  41  * off-load operation independent of the current Rx/Tx Ethernet offloads
  42  * supported within the rte_mbuf structure, and add supports for multiple
  43  * off-load operations and offload device types.
  44  *
  45  * The rte_mbuf_offload specifies the particular off-load operation type, such
  46  * as a crypto operation, and provides a container for the operations
  47  * parameter's inside the op union. These parameters are then used by the
  48  * device which supports that operation to perform the specified offload.
  49  *
  50  * This library provides an API to create pre-allocated mempool of offload
  51  * operations, with supporting allocate and free functions. It also provides
  52  * APIs for attaching an offload to a mbuf, as well as an API to retrieve a
  53  * specified offload type from an mbuf offload chain.
  54  */
  55
  56 #include <rte_mbuf.h>
  57 #include <rte_crypto.h>
  58
  59
  60 /** packet mbuf offload operation types */
  61 enum rte_mbuf_ol_op_type {
  62         RTE_PKTMBUF_OL_NOT_SPECIFIED = 0,
  63         /**< Off-load not specified */
  64         RTE_PKTMBUF_OL_CRYPTO
  65         /**< Crypto offload operation */
  66 };
  67
  68 /**
  69  * Generic packet mbuf offload
  70  * This is used to specify a offload operation to be performed on a rte_mbuf.
  71  * Multiple offload operations can be chained to the same mbuf, but only a
  72  * single offload operation of a particular type can be in the chain
  73  */
  74 struct rte_mbuf_offload {
  75         struct rte_mbuf_offload *next;  /**< next offload in chain */
  76         struct rte_mbuf *m;             /**< mbuf offload is attached to */
  77         struct rte_mempool *mp;         /**< mempool offload allocated from */
  78
  79         enum rte_mbuf_ol_op_type type;  /**< offload type */
  80         union {
  81                 struct rte_crypto_op crypto;    /**< Crypto operation */
  82         } op;
  83 };
  84
  85 /**< private data structure belonging to packet mbug offload mempool */
  86 struct rte_pktmbuf_offload_pool_private {
  87         uint16_t offload_priv_size;
  88         /**< Size of private area in each mbuf_offload. */
  89 };
  90
  91
  92 /**
  93  * Creates a mempool of rte_mbuf_offload objects
  94  *
  95  * @param       name            mempool name
  96  * @param       size            number of objects in mempool
  97  * @param       cache_size      cache size of objects for each core
  98  * @param       priv_size       size of private data to be allocated with each
  99  *                              rte_mbuf_offload object
 100  * @param       socket_id       Socket on which to allocate mempool objects
 101  *
 102  * @return
 103  * - On success returns a valid mempool of rte_mbuf_offload objects
 104  * - On failure return NULL
 105  */
 106 extern struct rte_mempool *
 107 rte_pktmbuf_offload_pool_create(const char *name, unsigned size,
 108                 unsigned cache_size, uint16_t priv_size, int socket_id);
 109
 110
 111 /**
 112  * Returns private data size allocated with each rte_mbuf_offload object by
 113  * the mempool
 114  *
 115  * @param       mpool   rte_mbuf_offload mempool
 116  *
 117  * @return      private data size
 118  */
 119 static inline uint16_t
 120 __rte_pktmbuf_offload_priv_size(struct rte_mempool *mpool)
 121 {
 122         struct rte_pktmbuf_offload_pool_private *priv =
 123                         rte_mempool_get_priv(mpool);
 124
 125         return priv->offload_priv_size;
 126 }
 127
 128 /**
 129  * Get specified off-load operation type from mbuf.
 130  *
 131  * @param       m               packet mbuf.
 132  * @param       type            offload operation type requested.
 133  *
 134  * @return
 135  * - On success retruns rte_mbuf_offload pointer
 136  * - On failure returns NULL
 137  *
 138  */
 139 static inline struct rte_mbuf_offload *
 140 rte_pktmbuf_offload_get(struct rte_mbuf *m, enum rte_mbuf_ol_op_type type)
 141 {
 142         struct rte_mbuf_offload *ol;
 143
 144         for (ol = m->offload_ops; ol != NULL; ol = ol->next)
 145                 if (ol->type == type)
 146                         return ol;
 147
 148         return ol;
 149 }
 150
 151 /**
 152  * Attach a rte_mbuf_offload to a mbuf. We only support a single offload of any
 153  * one type in our chain of offloads.
 154  *
 155  * @param       m       packet mbuf.
 156  * @param       ol      rte_mbuf_offload strucutre to be attached
 157  *
 158  * @returns
 159  * - On success returns the pointer to the offload we just added
 160  * - On failure returns NULL
 161  */
 162 static inline struct rte_mbuf_offload *
 163 rte_pktmbuf_offload_attach(struct rte_mbuf *m, struct rte_mbuf_offload *ol)
 164 {
 165         struct rte_mbuf_offload **ol_last;
 166
 167         for (ol_last = &m->offload_ops; ol_last[0] != NULL;
 168                         ol_last = &ol_last[0]->next)
 169                 if (ol_last[0]->type == ol->type)
 170                         return NULL;
 171
 172         ol_last[0] = ol;
 173         ol_last[0]->m = m;
 174         ol_last[0]->next = NULL;
 175
 176         return ol_last[0];
 177 }
 178
 179
 180 /** Rearms rte_mbuf_offload default parameters */
 181 static inline void
 182 __rte_pktmbuf_offload_reset(struct rte_mbuf_offload *ol,
 183                 enum rte_mbuf_ol_op_type type)
 184 {
 185         ol->m = NULL;
 186         ol->type = type;
 187
 188         switch (type) {
 189         case RTE_PKTMBUF_OL_CRYPTO:
 190                 __rte_crypto_op_reset(&ol->op.crypto); break;
 191         default:
 192                 break;
 193         }
 194 }
 195
 196 /** Allocate rte_mbuf_offload from mempool */
 197 static inline struct rte_mbuf_offload *
 198 __rte_pktmbuf_offload_raw_alloc(struct rte_mempool *mp)
 199 {
 200         void *buf = NULL;
 201
 202         if (rte_mempool_get(mp, &buf) < 0)
 203                 return NULL;
 204
 205         return (struct rte_mbuf_offload *)buf;
 206 }
 207
 208 /**
 209  * Allocate a rte_mbuf_offload with a specified operation type from
 210  * rte_mbuf_offload mempool
 211  *
 212  * @param       mpool           rte_mbuf_offload mempool
 213  * @param       type            offload operation type
 214  *
 215  * @returns
 216  * - On success returns a valid rte_mbuf_offload structure
 217  * - On failure returns NULL
 218  */
 219 static inline struct rte_mbuf_offload *
 220 rte_pktmbuf_offload_alloc(struct rte_mempool *mpool,
 221                 enum rte_mbuf_ol_op_type type)
 222 {
 223         struct rte_mbuf_offload *ol = __rte_pktmbuf_offload_raw_alloc(mpool);
 224
 225         if (ol != NULL)
 226                 __rte_pktmbuf_offload_reset(ol, type);
 227
 228         return ol;
 229 }
 230
 231 /**
 232  * free rte_mbuf_offload structure
 233  */
 234 static inline void
 235 rte_pktmbuf_offload_free(struct rte_mbuf_offload *ol)
 236 {
 237         if (ol != NULL && ol->mp != NULL)
 238                 rte_mempool_put(ol->mp, ol);
 239 }
 240
 241 /**
 242  * Checks if the private data of a rte_mbuf_offload has enough capacity for
 243  * requested size
 244  *
 245  * @returns
 246  * - if sufficient space available returns pointer to start of private data
 247  * - if insufficient space returns NULL
 248  */
 249 static inline void *
 250 __rte_pktmbuf_offload_check_priv_data_size(struct rte_mbuf_offload *ol,
 251                 uint16_t size)
 252 {
 253         uint16_t priv_size;
 254
 255         if (likely(ol->mp != NULL)) {
 256                 priv_size = __rte_pktmbuf_offload_priv_size(ol->mp);
 257
 258                 if (likely(priv_size >= size))
 259                         return (void *)(ol + 1);
 260         }
 261         return NULL;
 262 }
 263
 264 /**
 265  * Allocate space for crypto xforms in the private data space of the
 266  * rte_mbuf_offload. This also defaults the crypto xform type and configures
 267  * the chaining of the xform in the crypto operation
 268  *
 269  * @return
 270  * - On success returns pointer to first crypto xform in crypto operations chain
 271  * - On failure returns NULL
 272  */
 273 static inline struct rte_crypto_xform *
 274 rte_pktmbuf_offload_alloc_crypto_xforms(struct rte_mbuf_offload *ol,
 275                 unsigned nb_xforms)
 276 {
 277         struct rte_crypto_xform *xform;
 278         void *priv_data;
 279         uint16_t size;
 280
 281         size = sizeof(struct rte_crypto_xform) * nb_xforms;
 282         priv_data = __rte_pktmbuf_offload_check_priv_data_size(ol, size);
 283
 284         if (priv_data == NULL)
 285                 return NULL;
 286
 287         ol->op.crypto.xform = xform = (struct rte_crypto_xform *)priv_data;
 288
 289         do {
 290                 xform->type = RTE_CRYPTO_XFORM_NOT_SPECIFIED;
 291                 xform = xform->next = --nb_xforms > 0 ? xform + 1 : NULL;
 292         } while (xform);
 293
 294         return ol->op.crypto.xform;
 295 }
 296
 297
 298 #ifdef __cplusplus
 299 }
 300 #endif
 301
 302 #endif /* _RTE_MBUF_OFFLOAD_H_ */