sys/dev/isci/scil/sci_pool.h

   1 /*-
   2  * This file is provided under a dual BSD/GPLv2 license.  When using or
   3  * redistributing this file, you may do so under either license.
   4  *
   5  * GPL LICENSE SUMMARY
   6  *
   7  * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved.
   8  *
   9  * This program is free software; you can redistribute it and/or modify
  10  * it under the terms of version 2 of the GNU General Public License as
  11  * published by the Free Software Foundation.
  12  *
  13  * This program is distributed in the hope that it will be useful, but
  14  * WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16  * General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU General Public License
  19  * along with this program; if not, write to the Free Software
  20  * Foundation, Inc., 51 Franklin St - Fifth Floor, Boston, MA 02110-1301 USA.
  21  * The full GNU General Public License is included in this distribution
  22  * in the file called LICENSE.GPL.
  23  *
  24  * BSD LICENSE
  25  *
  26  * Copyright(c) 2008 - 2011 Intel Corporation. All rights reserved.
  27  * All rights reserved.
  28  *
  29  * Redistribution and use in source and binary forms, with or without
  30  * modification, are permitted provided that the following conditions
  31  * are met:
  32  *
  33  *   * Redistributions of source code must retain the above copyright
  34  *     notice, this list of conditions and the following disclaimer.
  35  *   * Redistributions in binary form must reproduce the above copyright
  36  *     notice, this list of conditions and the following disclaimer in
  37  *     the documentation and/or other materials provided with the
  38  *     distribution.
  39  *
  40  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  41  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  42  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  43  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  44  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  45  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  46  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  47  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  48  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  49  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  50  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  51  *
  52  * $FreeBSD$
  53  */
  54 /**
  55  * @file
  56  *
  57  * @brief This file contains the interface to the pool class.
  58  *        This class allows two different two different priority tasks to
  59  *        insert and remove items from the free pool. The user of the pool
  60  *        is expected to evaluate the pool condition empty before a get
  61  *        operation and pool condition full before a put operation.
  62  *        Methods Provided:
  63  *        - sci_pool_create()
  64  *        - sci_pool_initialize()
  65  *        - sci_pool_empty()
  66  *        - sci_pool_full()
  67  *        - sci_pool_get()
  68  *        - sci_pool_put()
  69  */
  70
  71 #ifndef _SCI_POOL_H_
  72 #define _SCI_POOL_H_
  73
  74 #include <dev/isci/types.h>
  75
  76 /**
  77  * Private operation for the pool
  78  */
  79 #define SCI_POOL_INCREMENT(this_pool, index) \
  80   (((index) + 1) == (this_pool).size ? 0 : (index) + 1)
  81
  82 /**
  83  * This creates a pool structure of pool_name. The members in the pool are
  84  * of type with number of elements equal to size.
  85  */
  86 #define SCI_POOL_CREATE(pool_name, type, pool_size) \
  87 struct \
  88 { \
  89    U32 size; \
  90    U32 get; \
  91    U32 put; \
  92    type array[(pool_size) + 1]; \
  93 } pool_name
  94
  95
  96 /**
  97  * This macro evaluates the pool and returns TRUE if the pool is empty.
  98  * If the pool is empty the user should not perform any get operation on
  99  * the pool.
 100  */
 101 #define sci_pool_empty(this_pool) \
 102    ((this_pool).get == (this_pool).put)
 103
 104 /**
 105  * This macro evaluates the pool and returns TRUE if the pool is full.  If
 106  * the pool is full the user should not perform any put operation.
 107  */
 108 #define sci_pool_full(this_pool) \
 109    (SCI_POOL_INCREMENT(this_pool, (this_pool).put) == (this_pool).get)
 110
 111 /**
 112  * This macro returns the size of the pool created.  The internal size
 113  * of the pool is actually 1 larger then necessary in order to ensure
 114  * get and put pointers can be written simultaneously by different
 115  * users.  As a result, this macro subtracts 1 from the internal size
 116  */
 117 #define sci_pool_size(this_pool) \
 118    ((this_pool).size - 1)
 119
 120 /**
 121  * This macro indicates the number of elements currently contained in the
 122  * pool.
 123  */
 124 #define sci_pool_count(this_pool) \
 125    ( \
 126       sci_pool_empty((this_pool)) \
 127       ? 0 \
 128       : ( \
 129            sci_pool_full((this_pool)) \
 130            ? sci_pool_size((this_pool)) \
 131            : ( \
 132                 (this_pool).get > (this_pool).put \
 133                 ? ((this_pool).size - (this_pool).get + (this_pool).put) \
 134                 : ((this_pool).put - (this_pool).get) \
 135              ) \
 136         ) \
 137    )
 138
 139 /**
 140  * This macro initializes the pool to an empty condition.
 141  */
 142 #define sci_pool_initialize(this_pool) \
 143 { \
 144    (this_pool).size = (sizeof((this_pool).array) / sizeof((this_pool).array[0])); \
 145    (this_pool).get = 0; \
 146    (this_pool).put = 0; \
 147 }
 148
 149 /**
 150  * This macro will get the next free element from the pool.
 151  * This should only be called if the pool is not empty.
 152  */
 153 #define sci_pool_get(this_pool, my_value) \
 154 { \
 155    (my_value) = (this_pool).array[(this_pool).get]; \
 156    (this_pool).get = SCI_POOL_INCREMENT((this_pool), (this_pool).get); \
 157 }
 158
 159 /**
 160  * This macro will put the value into the pool.
 161  * This should only be called if the pool is not full.
 162  */
 163 #define sci_pool_put(this_pool, the_value) \
 164 { \
 165    (this_pool).array[(this_pool).put] = (the_value); \
 166    (this_pool).put = SCI_POOL_INCREMENT((this_pool), (this_pool).put); \
 167 }
 168
 169 /**
 170  * This macro will search the pool and remove any elements in the pool
 171  * matching the supplied value.
 172  * @note This method can only be utilized on pools
 173  */
 174 #define sci_pool_erase(this_pool, type, the_value) \
 175 { \
 176    type tmp_value; \
 177    U32 index; \
 178    U32 element_count = sci_pool_count((this_pool)); \
 179  \
 180    for (index = 0; index < element_count; index++) \
 181    { \
 182       sci_pool_get((this_pool), tmp_value); \
 183       if (tmp_value != (the_value)) \
 184          sci_pool_put((this_pool), tmp_value); \
 185    } \
 186 }
 187
 188 #endif // _SCI_POOL_H_