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