lib/librte_mbuf_offload/rte_mbuf_offload.h

   1 /*-
   2  *   BSD LICENSE
   3  *
   4  *   Copyright(c) 2015-2016 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  * @warning
  56  * @b EXPERIMENTAL: this API may change without prior notice
  57  */
  58
  59 #include <rte_mbuf.h>
  60 #include <rte_crypto.h>
  61
  62 #ifdef __cplusplus
  63 extern "C" {
  64 #endif
  65
  66 /** packet mbuf offload operation types */
  67 enum rte_mbuf_ol_op_type {
  68         RTE_PKTMBUF_OL_NOT_SPECIFIED = 0,
  69         /**< Off-load not specified */
  70         RTE_PKTMBUF_OL_CRYPTO_SYM
  71         /**< Crypto offload operation */
  72 };
  73
  74 /**
  75  * Generic packet mbuf offload
  76  * This is used to specify a offload operation to be performed on a rte_mbuf.
  77  * Multiple offload operations can be chained to the same mbuf, but only a
  78  * single offload operation of a particular type can be in the chain
  79  */
  80 struct rte_mbuf_offload {
  81         struct rte_mbuf_offload *next;  /**< next offload in chain */
  82         struct rte_mbuf *m;             /**< mbuf offload is attached to */
  83         struct rte_mempool *mp;         /**< mempool offload allocated from */
  84
  85         enum rte_mbuf_ol_op_type type;  /**< offload type */
  86         union {
  87                 struct rte_crypto_sym_op crypto;        /**< Crypto operation */
  88         } op;
  89 };
  90
  91 /**< private data structure belonging to packet mbug offload mempool */
  92 struct rte_pktmbuf_offload_pool_private {
  93         uint16_t offload_priv_size;
  94         /**< Size of private area in each mbuf_offload. */
  95 };
  96
  97
  98 /**
  99  * Creates a mempool of rte_mbuf_offload objects
 100  *
 101  * EXPERIMENTAL: this API file may change without prior notice
 102  *
 103  * @param       name            mempool name
 104  * @param       size            number of objects in mempool
 105  * @param       cache_size      cache size of objects for each core
 106  * @param       priv_size       size of private data to be allocated with each
 107  *                              rte_mbuf_offload object
 108  * @param       socket_id       Socket on which to allocate mempool objects
 109  *
 110  * @return
 111  * - On success returns a valid mempool of rte_mbuf_offload objects
 112  * - On failure return NULL
 113  */
 114 extern struct rte_mempool *
 115 rte_pktmbuf_offload_pool_create(const char *name, unsigned size,
 116                 unsigned cache_size, uint16_t priv_size, int socket_id);
 117
 118
 119 /**
 120  * Returns private data size allocated with each rte_mbuf_offload object by
 121  * the mempool
 122  *
 123  * @param       mpool   rte_mbuf_offload mempool
 124  *
 125  * @return      private data size
 126  */
 127 static inline uint16_t
 128 __rte_pktmbuf_offload_priv_size(struct rte_mempool *mpool)
 129 {
 130         struct rte_pktmbuf_offload_pool_private *priv =
 131                 (struct rte_pktmbuf_offload_pool_private *)rte_mempool_get_priv(mpool);
 132
 133         return priv->offload_priv_size;
 134 }
 135
 136 /**
 137  * Get specified off-load operation type from mbuf.
 138  *
 139  * @param       m               packet mbuf.
 140  * @param       type            offload operation type requested.
 141  *
 142  * @return
 143  * - On success retruns rte_mbuf_offload pointer
 144  * - On failure returns NULL
 145  *
 146  */
 147 static inline struct rte_mbuf_offload *
 148 rte_pktmbuf_offload_get(struct rte_mbuf *m, enum rte_mbuf_ol_op_type type)
 149 {
 150         struct rte_mbuf_offload *ol;
 151
 152         for (ol = m->offload_ops; ol != NULL; ol = ol->next)
 153                 if (ol->type == type)
 154                         return ol;
 155
 156         return ol;
 157 }
 158
 159 /**
 160  * Attach a rte_mbuf_offload to a mbuf. We only support a single offload of any
 161  * one type in our chain of offloads.
 162  *
 163  * @param       m       packet mbuf.
 164  * @param       ol      rte_mbuf_offload strucutre to be attached
 165  *
 166  * @returns
 167  * - On success returns the pointer to the offload we just added
 168  * - On failure returns NULL
 169  */
 170 static inline struct rte_mbuf_offload *
 171 rte_pktmbuf_offload_attach(struct rte_mbuf *m, struct rte_mbuf_offload *ol)
 172 {
 173         struct rte_mbuf_offload **ol_last;
 174
 175         for (ol_last = &m->offload_ops; ol_last[0] != NULL;
 176                         ol_last = &ol_last[0]->next)
 177                 if (ol_last[0]->type == ol->type)
 178                         return NULL;
 179
 180         ol_last[0] = ol;
 181         ol_last[0]->m = m;
 182         ol_last[0]->next = NULL;
 183
 184         return ol_last[0];
 185 }
 186
 187
 188 /** Rearms rte_mbuf_offload default parameters */
 189 static inline void
 190 __rte_pktmbuf_offload_reset(struct rte_mbuf_offload *ol,
 191                 enum rte_mbuf_ol_op_type type)
 192 {
 193         ol->m = NULL;
 194         ol->type = type;
 195
 196         switch (type) {
 197         case RTE_PKTMBUF_OL_CRYPTO_SYM:
 198                 __rte_crypto_sym_op_reset(&ol->op.crypto); break;
 199         default:
 200                 break;
 201         }
 202 }
 203
 204 /** Allocate rte_mbuf_offload from mempool */
 205 static inline struct rte_mbuf_offload *
 206 __rte_pktmbuf_offload_raw_alloc(struct rte_mempool *mp)
 207 {
 208         void *buf = NULL;
 209
 210         if (rte_mempool_get(mp, &buf) < 0)
 211                 return NULL;
 212
 213         return (struct rte_mbuf_offload *)buf;
 214 }
 215
 216 /**
 217  * Allocate a rte_mbuf_offload with a specified operation type from
 218  * rte_mbuf_offload mempool
 219  *
 220  * @param       mpool           rte_mbuf_offload mempool
 221  * @param       type            offload operation type
 222  *
 223  * @returns
 224  * - On success returns a valid rte_mbuf_offload structure
 225  * - On failure returns NULL
 226  */
 227 static inline struct rte_mbuf_offload *
 228 rte_pktmbuf_offload_alloc(struct rte_mempool *mpool,
 229                 enum rte_mbuf_ol_op_type type)
 230 {
 231         struct rte_mbuf_offload *ol = __rte_pktmbuf_offload_raw_alloc(mpool);
 232
 233         if (ol != NULL)
 234                 __rte_pktmbuf_offload_reset(ol, type);
 235
 236         return ol;
 237 }
 238
 239 /**
 240  * free rte_mbuf_offload structure
 241  */
 242 static inline void
 243 rte_pktmbuf_offload_free(struct rte_mbuf_offload *ol)
 244 {
 245         if (ol != NULL && ol->mp != NULL)
 246                 rte_mempool_put(ol->mp, ol);
 247 }
 248
 249 /**
 250  * Checks if the private data of a rte_mbuf_offload has enough capacity for
 251  * requested size
 252  *
 253  * @returns
 254  * - if sufficient space available returns pointer to start of private data
 255  * - if insufficient space returns NULL
 256  */
 257 static inline void *
 258 __rte_pktmbuf_offload_check_priv_data_size(struct rte_mbuf_offload *ol,
 259                 uint16_t size)
 260 {
 261         uint16_t priv_size;
 262
 263         if (likely(ol->mp != NULL)) {
 264                 priv_size = __rte_pktmbuf_offload_priv_size(ol->mp);
 265
 266                 if (likely(priv_size >= size))
 267                         return (void *)(ol + 1);
 268         }
 269         return NULL;
 270 }
 271
 272 /**
 273  * Allocate space for crypto xforms in the private data space of the
 274  * rte_mbuf_offload. This also defaults the crypto xform type and configures
 275  * the chaining of the xform in the crypto operation
 276  *
 277  * @return
 278  * - On success returns pointer to first crypto xform in crypto operations chain
 279  * - On failure returns NULL
 280  */
 281 static inline struct rte_crypto_sym_xform *
 282 rte_pktmbuf_offload_alloc_crypto_sym_xforms(struct rte_mbuf_offload *ol,
 283                 unsigned nb_xforms)
 284 {
 285         struct rte_crypto_sym_xform *xform;
 286         void *priv_data;
 287         uint16_t size;
 288
 289         size = sizeof(struct rte_crypto_sym_xform) * nb_xforms;
 290         priv_data = __rte_pktmbuf_offload_check_priv_data_size(ol, size);
 291
 292         if (priv_data == NULL)
 293                 return NULL;
 294
 295         ol->op.crypto.xform = xform = (struct rte_crypto_sym_xform *)priv_data;
 296
 297         do {
 298                 xform->type = RTE_CRYPTO_SYM_XFORM_NOT_SPECIFIED;
 299                 xform = xform->next = --nb_xforms > 0 ? xform + 1 : NULL;
 300         } while (xform);
 301
 302         return ol->op.crypto.xform;
 303 }
 304
 305
 306 #ifdef __cplusplus
 307 }
 308 #endif
 309
 310 #endif /* _RTE_MBUF_OFFLOAD_H_ */