drivers/net/npe/include/IxOsalBufferMgt.h

   1 /**
   2  * @file IxOsalBufferMgt.h
   3  *
   4  * @brief OSAL Buffer pool management and buffer management definitions.
   5  *
   6  * Design Notes:
   7  *
   8  * @par
   9  * IXP400 SW Release version 2.0
  10  *
  11  * -- Copyright Notice --
  12  *
  13  * @par
  14  * Copyright 2001-2005, Intel Corporation.
  15  * All rights reserved.
  16  *
  17  * @par
  18  * SPDX-License-Identifier:     BSD-3-Clause
  19  * @par
  20  * -- End of Copyright Notice --
  21  */
  22 /* @par
  23  * -- Copyright Notice --
  24  *
  25  * @par
  26  * Copyright 1979, 1980, 1983, 1986, 1988, 1989, 1991, 1992, 1993, 1994
  27  *      The Regents of the University of California. All rights reserved.
  28  * @par
  29  * -- End of Copyright Notice --
  30  */
  31
  32 #ifndef IxOsalBufferMgt_H
  33 #define IxOsalBufferMgt_H
  34
  35 #include "IxOsal.h"
  36 /**
  37  * @defgroup IxOsalBufferMgt OSAL Buffer Management Module.
  38  *
  39  * @brief Buffer management module for IxOsal
  40  *
  41  * @{
  42  */
  43
  44 /**
  45  * @ingroup IxOsalBufferMgt
  46  *
  47  * @def IX_OSAL_MBUF_MAX_POOLS
  48  *
  49  * @brief The maximum number of pools that can be allocated, must be
  50  *        a multiple of 32 as required by implementation logic.
  51  * @note  This can safely be increased if more pools are required.
  52  */
  53 #define IX_OSAL_MBUF_MAX_POOLS      32
  54
  55 /**
  56  * @ingroup IxOsalBufferMgt
  57  *
  58  * @def IX_OSAL_MBUF_POOL_NAME_LEN
  59  *
  60  * @brief The maximum string length of the pool name
  61  */
  62 #define IX_OSAL_MBUF_POOL_NAME_LEN  64
  63
  64
  65
  66 /**
  67  *  Define IX_OSAL_MBUF
  68  */
  69
  70
  71 /* forward declaration of internal structure */
  72 struct __IXP_BUF;
  73
  74 /*
  75  * OS can define it in IxOsalOs.h to skip the following
  76  * definition.
  77  */
  78 #ifndef IX_OSAL_ATTRIBUTE_ALIGN32
  79 #define IX_OSAL_ATTRIBUTE_ALIGN32 __attribute__ ((aligned(32)))
  80 #endif
  81
  82 /* release v1.4 backward compatible definitions */
  83 struct __IX_MBUF
  84 {
  85     struct __IXP_BUF *ix_next IX_OSAL_ATTRIBUTE_ALIGN32;
  86     struct __IXP_BUF *ix_nextPacket;
  87     UINT8 *ix_data;
  88     UINT32 ix_len;
  89     unsigned char ix_type;
  90     unsigned char ix_flags;
  91     unsigned short ix_reserved;
  92     UINT32 ix_rsvd;
  93     UINT32 ix_PktLen;
  94     void *ix_priv;
  95 };
  96
  97 struct __IX_CTRL
  98 {
  99     UINT32 ix_reserved[2];        /**< Reserved field */
 100     UINT32 ix_signature;          /**< Field to indicate if buffers are allocated by the system */
 101     UINT32 ix_allocated_len;      /**< Allocated buffer length */
 102     UINT32 ix_allocated_data;     /**< Allocated buffer data pointer */
 103     void *ix_pool;                /**< pointer to the buffer pool */
 104     struct __IXP_BUF *ix_chain;   /**< chaining */
 105     void *ix_osbuf_ptr;           /**< Storage for OS-specific buffer pointer */
 106 };
 107
 108 struct __IX_NE_SHARED
 109 {
 110     UINT32 reserved[8] IX_OSAL_ATTRIBUTE_ALIGN32;   /**< Reserved area for NPE Service-specific usage */
 111 };
 112
 113
 114 /*
 115  * IXP buffer structure
 116  */
 117 typedef struct __IXP_BUF
 118 {
 119     struct __IX_MBUF ix_mbuf IX_OSAL_ATTRIBUTE_ALIGN32; /**< buffer header */
 120     struct __IX_CTRL ix_ctrl;                           /**< buffer management */
 121     struct __IX_NE_SHARED ix_ne;                        /**< Reserved area for NPE Service-specific usage*/
 122 } IXP_BUF;
 123
 124
 125
 126 /**
 127  * @ingroup IxOsalBufferMgt
 128  *
 129  * @def typedef IX_OSAL_MBUF
 130  *
 131  * @brief Generic IXP mbuf format.
 132  */
 133 typedef IXP_BUF IX_OSAL_MBUF;
 134
 135
 136 /**
 137  * @ingroup IxOsalBufferMgt
 138  *
 139  * @def IX_OSAL_IXP_NEXT_BUFFER_IN_PKT_PTR(m_blk_ptr)
 140  *
 141  * @brief Return pointer to the next mbuf in a single packet
 142  */
 143 #define IX_OSAL_MBUF_NEXT_BUFFER_IN_PKT_PTR(m_blk_ptr)  \
 144         (m_blk_ptr)->ix_mbuf.ix_next
 145
 146
 147 /**
 148  * @ingroup IxOsalBufferMgt
 149  *
 150  * @def IX_OSAL_MBUF_NEXT_PKT_IN_CHAIN_PTR(m_blk_ptr)
 151  *
 152  * @brief Return pointer to the next packet in the chain
 153  */
 154 #define IX_OSAL_MBUF_NEXT_PKT_IN_CHAIN_PTR(m_blk_ptr)  \
 155         (m_blk_ptr)->ix_mbuf.ix_nextPacket
 156
 157
 158 /**
 159  * @ingroup IxOsalBufferMgt
 160  *
 161  * @def IX_OSAL_MBUF_MDATA(m_blk_ptr)
 162  *
 163  * @brief Return pointer to the data in the mbuf
 164  */
 165 #define IX_OSAL_MBUF_MDATA(m_blk_ptr)       (m_blk_ptr)->ix_mbuf.ix_data
 166
 167 /**
 168  * @ingroup IxOsalBufferMgt
 169  *
 170  * @def IX_OSAL_MBUF_MLEN(m_blk_ptr)
 171  *
 172  * @brief Return the data length
 173  */
 174 #define IX_OSAL_MBUF_MLEN(m_blk_ptr) \
 175     (m_blk_ptr)->ix_mbuf.ix_len
 176
 177 /**
 178  * @ingroup IxOsalBufferMgt
 179  *
 180  * @def IX_OSAL_MBUF_MTYPE(m_blk_ptr)
 181  *
 182  * @brief Return the data type in the mbuf
 183  */
 184 #define IX_OSAL_MBUF_MTYPE(m_blk_ptr) \
 185     (m_blk_ptr)->ix_mbuf.ix_type
 186
 187
 188 /**
 189  * @ingroup IxOsalBufferMgt
 190  *
 191  * @def IX_OSAL_MBUF_FLAGS(m_blk_ptr)
 192  *
 193  * @brief Return the buffer flags
 194  */
 195 #define IX_OSAL_MBUF_FLAGS(m_blk_ptr)       \
 196         (m_blk_ptr)->ix_mbuf.ix_flags
 197
 198
 199 /**
 200  * @ingroup IxOsalBufferMgt
 201  *
 202  * @def IX_OSAL_MBUF_NET_POOL(m_blk_ptr)
 203  *
 204  * @brief Return pointer to a network pool
 205  */
 206 #define IX_OSAL_MBUF_NET_POOL(m_blk_ptr)        \
 207         (m_blk_ptr)->ix_ctrl.ix_pool
 208
 209
 210
 211 /**
 212  * @ingroup IxOsalBufferMgt
 213  *
 214  * @def IX_OSAL_MBUF_PKT_LEN(m_blk_ptr)
 215  *
 216  * @brief Return the total length of all the data in
 217  * the mbuf chain for this packet
 218  */
 219 #define IX_OSAL_MBUF_PKT_LEN(m_blk_ptr) \
 220         (m_blk_ptr)->ix_mbuf.ix_PktLen
 221
 222
 223
 224
 225 /**
 226  * @ingroup IxOsalBufferMgt
 227  *
 228  * @def IX_OSAL_MBUF_PRIV(m_blk_ptr)
 229  *
 230  * @brief Return the private field
 231  */
 232 #define IX_OSAL_MBUF_PRIV(m_blk_ptr)        \
 233         (m_blk_ptr)->ix_mbuf.ix_priv
 234
 235
 236
 237 /**
 238  * @ingroup IxOsalBufferMgt
 239  *
 240  * @def IX_OSAL_MBUF_SIGNATURE(m_blk_ptr)
 241  *
 242  * @brief Return the signature field of IX_OSAL_MBUF
 243  */
 244 #define IX_OSAL_MBUF_SIGNATURE(m_blk_ptr)  \
 245         (m_blk_ptr)->ix_ctrl.ix_signature
 246
 247
 248 /**
 249  * @ingroup IxOsalBufferMgt
 250  *
 251  * @def IX_OSAL_MBUF_OSBUF_PTR(m_blk_ptr)
 252  *
 253  * @brief Return ix_osbuf_ptr field of IX_OSAL_MBUF, which is used to store OS-specific buffer pointer during a buffer conversion.
 254  */
 255 #define IX_OSAL_MBUF_OSBUF_PTR(m_blk_ptr)  \
 256         (m_blk_ptr)->ix_ctrl.ix_osbuf_ptr
 257
 258
 259 /**
 260  * @ingroup IxOsalBufferMgt
 261  *
 262  * @def IX_OSAL_MBUF_ALLOCATED_BUFF_LEN(m_blk_ptr)
 263  *
 264  * @brief Return the allocated buffer size
 265  */
 266 #define IX_OSAL_MBUF_ALLOCATED_BUFF_LEN(m_blk_ptr)  \
 267         (m_blk_ptr)->ix_ctrl.ix_allocated_len
 268
 269 /**
 270  * @ingroup IxOsalBufferMgt
 271  *
 272  * @def IX_OSAL_MBUF_ALLOCATED_BUFF_DATA(m_blk_ptr)
 273  *
 274  * @brief Return the allocated buffer pointer
 275  */
 276 #define IX_OSAL_MBUF_ALLOCATED_BUFF_DATA(m_blk_ptr)  \
 277         (m_blk_ptr)->ix_ctrl.ix_allocated_data
 278
 279
 280
 281 /* Name length */
 282 #define IX_OSAL_MBUF_POOL_NAME_LEN  64
 283
 284
 285 /****************************************************
 286  * Macros for buffer pool management
 287  ****************************************************/
 288
 289 /**
 290  * @ingroup IxOsalBufferMgt
 291  *
 292  * @def IX_OSAL_MBUF_POOL_FREE_COUNT(m_pool_ptr
 293  *
 294  * @brief Return the total number of freed buffers left in the pool.
 295  */
 296 #define IX_OSAL_MBUF_POOL_FREE_COUNT(m_pool_ptr) \
 297                     ixOsalBuffPoolFreeCountGet(m_pool_ptr)
 298
 299 /**
 300  * @ingroup IxOsalBufferMgt
 301  *
 302  * @def IX_OSAL_MBUF_POOL_SIZE_ALIGN
 303  *
 304  * @brief This macro takes an integer as an argument and
 305  * rounds it up to be a multiple of the memory cache-line
 306  * size.
 307  *
 308  * @param int [in] size - the size integer to be rounded up
 309  *
 310  * @return int - the size, rounded up to a multiple of
 311  *               the cache-line size
 312  */
 313 #define IX_OSAL_MBUF_POOL_SIZE_ALIGN(size)                 \
 314     ((((size) + (IX_OSAL_CACHE_LINE_SIZE - 1)) /      \
 315         IX_OSAL_CACHE_LINE_SIZE) *                  \
 316             IX_OSAL_CACHE_LINE_SIZE)
 317
 318 /* Don't use this directly, use macro */
 319 PUBLIC UINT32 ixOsalBuffPoolMbufAreaSizeGet (int count);
 320
 321
 322 /**
 323  * @ingroup IxOsalBufferMgt
 324  *
 325  * @def IX_OSAL_MBUF_POOL_MBUF_AREA_SIZE_ALIGNED
 326  *
 327  * @brief This macro calculates, from the number of mbufs required, the
 328  * size of the memory area required to contain the mbuf headers for the
 329  * buffers in the pool.  The size to be used for each mbuf header is
 330  * rounded up to a multiple of the cache-line size, to ensure
 331  * each mbuf header aligns on a cache-line boundary.
 332  * This macro is used by IX_OSAL_MBUF_POOL_MBUF_AREA_ALLOC()
 333  *
 334  * @param int [in] count - the number of buffers the pool will contain
 335  *
 336  * @return int - the total size required for the pool mbuf area (aligned)
 337  */
 338 #define IX_OSAL_MBUF_POOL_MBUF_AREA_SIZE_ALIGNED(count) \
 339         ixOsalBuffPoolMbufAreaSizeGet(count)
 340
 341
 342 /* Don't use this directly, use macro */
 343 PUBLIC UINT32 ixOsalBuffPoolDataAreaSizeGet (int count, int size);
 344
 345
 346 /**
 347  * @ingroup IxOsalBufferMgt
 348  *
 349  * @def IX_OSAL_MBUF_POOL_DATA_AREA_SIZE_ALIGNED
 350  *
 351  * @brief This macro calculates, from the number of mbufs required and the
 352  * size of the data portion for each mbuf, the size of the data memory area
 353  * required. The size is adjusted to ensure alignment on cache line boundaries.
 354  * This macro is used by IX_OSAL_MBUF_POOL_DATA_AREA_ALLOC()
 355  *
 356  *
 357  * @param int [in] count - The number of mbufs in the pool.
 358  * @param int [in] size  - The desired size for each mbuf data portion.
 359  *                         This size will be rounded up to a multiple of the
 360  *                         cache-line size to ensure alignment on cache-line
 361  *                         boundaries for each data block.
 362  *
 363  * @return int - the total size required for the pool data area (aligned)
 364  */
 365 #define IX_OSAL_MBUF_POOL_DATA_AREA_SIZE_ALIGNED(count, size) \
 366         ixOsalBuffPoolDataAreaSizeGet((count), (size))
 367
 368
 369 /**
 370  * @ingroup IxOsalBufferMgt
 371  *
 372  * @def IX_OSAL_MBUF_POOL_MBUF_AREA_ALLOC
 373  *
 374  * @brief Allocates the memory area needed for the number of mbuf headers
 375  * specified by <i>count</i>.
 376  * This macro ensures the mbuf headers align on cache line boundaries.
 377  * This macro evaluates to a pointer to the memory allocated.
 378  *
 379  * @param int [in] count - the number of mbufs the pool will contain
 380  * @param int [out] memAreaSize - the total amount of memory allocated
 381  *
 382  * @return void * - a pointer to the allocated memory area
 383  */
 384 #define IX_OSAL_MBUF_POOL_MBUF_AREA_ALLOC(count, memAreaSize) \
 385     IX_OSAL_CACHE_DMA_MALLOC((memAreaSize =                 \
 386         IX_OSAL_MBUF_POOL_MBUF_AREA_SIZE_ALIGNED(count)))
 387
 388 /**
 389  * @ingroup IxOsalBufferMgt
 390  *
 391  * @def IX_OSAL_MBUF_POOL_DATA_AREA_ALLOC
 392  *
 393  * @brief Allocates the memory pool for the data portion of the pool mbufs.
 394  * The number of mbufs is specified by <i>count</i>.  The size of the data
 395  * portion of each mbuf is specified by <i>size</i>.
 396  * This macro ensures the mbufs are aligned on cache line boundaries
 397  * This macro evaluates to a pointer to the memory allocated.
 398  *
 399  * @param int [in] count - the number of mbufs the pool will contain
 400  * @param int [in] size - the desired size (in bytes) required for the data
 401  *                        portion of each mbuf.  Note that this size may be
 402  *                        rounded up to ensure alignment on cache-line
 403  *                        boundaries.
 404  * @param int [out] memAreaSize - the total amount of memory allocated
 405  *
 406  * @return void * - a pointer to the allocated memory area
 407  */
 408 #define IX_OSAL_MBUF_POOL_DATA_AREA_ALLOC(count, size, memAreaSize) \
 409     IX_OSAL_CACHE_DMA_MALLOC((memAreaSize =                     \
 410         IX_OSAL_MBUF_POOL_DATA_AREA_SIZE_ALIGNED(count,size)))
 411
 412
 413
 414 /**
 415  * @ingroup IxOsalBufferMgt
 416  *
 417  * @def IX_OSAL_MBUF_POOL_INIT
 418  *
 419  * @brief Wrapper macro for ixOsalPoolInit()
 420  * See function description below for details.
 421  */
 422 #define IX_OSAL_MBUF_POOL_INIT(count, size, name) \
 423     ixOsalPoolInit((count), (size), (name))
 424
 425 /**
 426  * @ingroup IxOsalBufferMgt
 427  *
 428  * @def IX_OSAL_MBUF_NO_ALLOC_POOL_INIT
 429  *
 430  * @return Pointer to the new pool or NULL if the initialization failed.
 431  *
 432  * @brief Wrapper macro for ixOsalNoAllocPoolInit()
 433  * See function description below for details.
 434  *
 435  */
 436 #define IX_OSAL_MBUF_NO_ALLOC_POOL_INIT(bufPtr, dataPtr, count, size, name) \
 437     ixOsalNoAllocPoolInit( (bufPtr), (dataPtr), (count), (size), (name))
 438
 439 /**
 440  * @ingroup IxOsalBufferMgt
 441  *
 442  * @def IX_OSAL_MBUF_POOL_GET
 443  *
 444  * @brief Wrapper macro for ixOsalMbufAlloc()
 445  * See function description below for details.
 446  */
 447 #define IX_OSAL_MBUF_POOL_GET(poolPtr) \
 448         ixOsalMbufAlloc(poolPtr)
 449
 450 /**
 451  * @ingroup IxOsalBufferMgt
 452  *
 453  * @def IX_OSAL_MBUF_POOL_PUT
 454  *
 455  * @brief Wrapper macro for ixOsalMbufFree()
 456  * See function description below for details.
 457  */
 458 #define IX_OSAL_MBUF_POOL_PUT(bufPtr) \
 459     ixOsalMbufFree(bufPtr)
 460
 461 /**
 462  * @ingroup IxOsalBufferMgt
 463  *
 464  * @def IX_OSAL_MBUF_POOL_PUT_CHAIN
 465  *
 466  * @brief Wrapper macro for ixOsalMbufChainFree()
 467  * See function description below for details.
 468  */
 469 #define IX_OSAL_MBUF_POOL_PUT_CHAIN(bufPtr) \
 470     ixOsalMbufChainFree(bufPtr)
 471
 472 /**
 473  * @ingroup IxOsalBufferMgt
 474  *
 475  * @def IX_OSAL_MBUF_POOL_SHOW
 476  *
 477  * @brief Wrapper macro for ixOsalMbufPoolShow()
 478  * See function description below for details.
 479  */
 480 #define IX_OSAL_MBUF_POOL_SHOW(poolPtr) \
 481     ixOsalMbufPoolShow(poolPtr)
 482
 483 /**
 484  * @ingroup IxOsalBufferMgt
 485  *
 486  * @def IX_OSAL_MBUF_POOL_MDATA_RESET
 487  *
 488  * @brief Wrapper macro for ixOsalMbufDataPtrReset()
 489  * See function description below for details.
 490  */
 491 #define IX_OSAL_MBUF_POOL_MDATA_RESET(bufPtr) \
 492     ixOsalMbufDataPtrReset(bufPtr)
 493
 494 /**
 495  * @ingroup IxOsalBufferMgt
 496  *
 497  * @def IX_OSAL_MBUF_POOL_UNINIT
 498  *
 499  * @brief Wrapper macro for ixOsalBuffPoolUninit()
 500  * See function description below for details.
 501  */
 502 #define IX_OSAL_MBUF_POOL_UNINIT(m_pool_ptr)  \
 503         ixOsalBuffPoolUninit(m_pool_ptr)
 504
 505 /*
 506  * Include OS-specific bufferMgt definitions
 507  */
 508 #include "IxOsalOsBufferMgt.h"
 509
 510
 511 /**
 512  * @ingroup IxOsalBufferMgt
 513  *
 514  * @def IX_OSAL_CONVERT_OSBUF_TO_IXPBUF( osBufPtr, ixpBufPtr)
 515  *
 516  * @brief Convert pre-allocated os-specific buffer format to OSAL IXP_BUF (IX_OSAL_MBUF) format.
 517  * It is users' responsibility to provide pre-allocated and valid buffer pointers.
 518  * @param osBufPtr (in) - a pre-allocated os-specific buffer pointer.
 519  * @param ixpBufPtr (in)- a pre-allocated OSAL IXP_BUF pointer
 520  * @return None
 521  */
 522 #define IX_OSAL_CONVERT_OSBUF_TO_IXPBUF( osBufPtr, ixpBufPtr) \
 523         IX_OSAL_OS_CONVERT_OSBUF_TO_IXPBUF( osBufPtr, ixpBufPtr)
 524
 525
 526 /**
 527  * @ingroup IxOsalBufferMgt
 528  *
 529  * @def IX_OSAL_CONVERT_IXPBUF_TO_OSBUF( ixpBufPtr, osBufPtr)
 530  *
 531  * @brief Convert pre-allocated OSAL IXP_BUF (IX_OSAL_MBUF) format to os-specific buffer pointers.
 532  * @param ixpBufPtr (in) - OSAL IXP_BUF pointer
 533  * @param osBufPtr (out) - os-specific buffer pointer.
 534  * @return None
 535  */
 536
 537 #define IX_OSAL_CONVERT_IXPBUF_TO_OSBUF( ixpBufPtr, osBufPtr)  \
 538         IX_OSAL_OS_CONVERT_IXPBUF_TO_OSBUF( ixpBufPtr, osBufPtr)
 539
 540
 541 PUBLIC IX_OSAL_MBUF_POOL *ixOsalPoolInit (UINT32 count,
 542                       UINT32 size, const char *name);
 543
 544 PUBLIC IX_OSAL_MBUF_POOL *ixOsalNoAllocPoolInit (void *poolBufPtr,
 545                          void *poolDataPtr,
 546                                                  UINT32 count,
 547                                                  UINT32 size,
 548                                                  const char *name);
 549
 550 PUBLIC IX_OSAL_MBUF *ixOsalMbufAlloc (IX_OSAL_MBUF_POOL * pool);
 551
 552 PUBLIC IX_OSAL_MBUF *ixOsalMbufFree (IX_OSAL_MBUF * mbuf);
 553
 554 PUBLIC void ixOsalMbufChainFree (IX_OSAL_MBUF * mbuf);
 555
 556 PUBLIC void ixOsalMbufDataPtrReset (IX_OSAL_MBUF * mbuf);
 557
 558 PUBLIC void ixOsalMbufPoolShow (IX_OSAL_MBUF_POOL * pool);
 559
 560 PUBLIC IX_STATUS ixOsalBuffPoolUninit (IX_OSAL_MBUF_POOL * pool);
 561
 562 PUBLIC UINT32 ixOsalBuffPoolFreeCountGet(IX_OSAL_MBUF_POOL * pool);
 563
 564
 565 /**
 566  * @} IxOsalBufferMgt
 567  */
 568
 569
 570 #endif /* IxOsalBufferMgt_H */