FD.io VPP  v20.05.1-5-g09f167997
Vector Packet Processing
vec_bootstrap.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2015 Cisco and/or its affiliates.
3  * Licensed under the Apache License, Version 2.0 (the "License");
4  * you may not use this file except in compliance with the License.
5  * You may obtain a copy of the License at:
6  *
7  * http://www.apache.org/licenses/LICENSE-2.0
8  *
9  * Unless required by applicable law or agreed to in writing, software
10  * distributed under the License is distributed on an "AS IS" BASIS,
11  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12  * See the License for the specific language governing permissions and
13  * limitations under the License.
14  */
15 /*
16  Copyright (c) 2001, 2002, 2003 Eliot Dresselhaus
17 
18  Permission is hereby granted, free of charge, to any person obtaining
19  a copy of this software and associated documentation files (the
20  "Software"), to deal in the Software without restriction, including
21  without limitation the rights to use, copy, modify, merge, publish,
22  distribute, sublicense, and/or sell copies of the Software, and to
23  permit persons to whom the Software is furnished to do so, subject to
24  the following conditions:
25 
26  The above copyright notice and this permission notice shall be
27  included in all copies or substantial portions of the Software.
28 
29  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
30  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
31  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
32  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
33  LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
34  OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
35  WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
36 */
37 
38 #ifndef included_clib_vec_bootstrap_h
39 #define included_clib_vec_bootstrap_h
40 
41 /** \file
42  Vector bootstrap header file
43 */
44 
45 /* Bootstrap include so that #include <vppinfra/mem.h> can include e.g.
46  <vppinfra/mheap.h> which depends on <vppinfra/vec.h>. */
47 
48 /** \brief vector header structure
49 
50  Bookkeeping header preceding vector elements in memory.
51  User header information may preceed standard vec header.
52  If you change u32 len -> u64 len, single vectors can
53  exceed 2**32 elements. Clib heaps are vectors. */
54 
55 typedef struct
56 {
57  u32 len; /**< Number of elements in vector (NOT its allocated length). */
58  u8 numa_id; /**< NUMA id */
59  u8 vpad[3]; /**< pad to 8 bytes */
60  u8 vector_data[0]; /**< Vector data . */
61 } vec_header_t;
62 
63 #define VEC_NUMA_UNSPECIFIED (0xFF)
64 
65 /** \brief Find the vector header
66 
67  Given the user's pointer to a vector, find the corresponding
68  vector header
69 
70  @param v pointer to a vector
71  @return pointer to the vector's vector_header_t
72 */
73 #define _vec_find(v) ((vec_header_t *) (v) - 1)
74 
75 #define _vec_round_size(s) \
76  (((s) + sizeof (uword) - 1) &~ (sizeof (uword) - 1))
77 
79 vec_header_bytes (uword header_bytes)
80 {
81  return round_pow2 (header_bytes + sizeof (vec_header_t),
82  sizeof (vec_header_t));
83 }
84 
85 /** \brief Find a user vector header
86 
87  Finds the user header of a vector with unspecified alignment given
88  the user pointer to the vector.
89 */
90 
91 always_inline void *
92 vec_header (void *v, uword header_bytes)
93 {
94  return v - vec_header_bytes (header_bytes);
95 }
96 
97 /** \brief Find the end of user vector header
98 
99  Finds the end of the user header of a vector with unspecified
100  alignment given the user pointer to the vector.
101 */
102 
103 always_inline void *
104 vec_header_end (void *v, uword header_bytes)
105 {
106  return v + vec_header_bytes (header_bytes);
107 }
108 
110 vec_aligned_header_bytes (uword header_bytes, uword align)
111 {
112  return round_pow2 (header_bytes + sizeof (vec_header_t), align);
113 }
114 
115 always_inline void *
116 vec_aligned_header (void *v, uword header_bytes, uword align)
117 {
118  return v - vec_aligned_header_bytes (header_bytes, align);
119 }
120 
121 always_inline void *
122 vec_aligned_header_end (void *v, uword header_bytes, uword align)
123 {
124  return v + vec_aligned_header_bytes (header_bytes, align);
125 }
126 
127 
128 /** \brief Number of elements in vector (lvalue-capable)
129 
130  _vec_len (v) does not check for null, but can be used as an lvalue
131  (e.g. _vec_len (v) = 99).
132 */
133 
134 #define _vec_len(v) (_vec_find(v)->len)
135 
136 /** \brief Number of elements in vector (rvalue-only, NULL tolerant)
137 
138  vec_len (v) checks for NULL, but cannot be used as an lvalue.
139  If in doubt, use vec_len...
140 */
141 
142 #define vec_len(v) ((v) ? _vec_len(v) : 0)
143 
144 /** \brief Vector's NUMA id (lvalue-capable)
145 
146  _vec_numa(v) does not check for null, but can be used as an lvalue
147  (e.g. _vec_numa(v) = 1).
148 */
149 
150 #define _vec_numa(v) (_vec_find(v)->numa_id)
151 
152 /** \brief Return vector's NUMA ID (rvalue-only, NULL tolerant)
153  vec_numa(v) checks for NULL, but cannot be used as an lvalue.
154 */
155 #define vec_numa(v) ((v) ? _vec_numa(v) : 0)
156 
157 
158 /** \brief Number of data bytes in vector. */
159 
160 #define vec_bytes(v) (vec_len (v) * sizeof (v[0]))
161 
162 /** \brief Total number of bytes that can fit in vector with current allocation. */
163 
164 #define vec_capacity(v,b) \
165 ({ \
166  void * _vec_capacity_v = (void *) (v); \
167  uword _vec_capacity_b = (b); \
168  _vec_capacity_b = sizeof (vec_header_t) + _vec_round_size (_vec_capacity_b); \
169  _vec_capacity_v ? clib_mem_size (_vec_capacity_v - _vec_capacity_b) : 0; \
170 })
171 
172 /** \brief Total number of elements that can fit into vector. */
173 #define vec_max_len(v) (vec_capacity(v,0) / sizeof (v[0]))
174 
175 /** \brief Set vector length to a user-defined value */
176 #ifndef __COVERITY__ /* Coverity gets confused by ASSERT() */
177 #define vec_set_len(v, l) do { \
178  ASSERT(v); \
179  ASSERT((l) <= vec_max_len(v)); \
180  CLIB_MEM_POISON_LEN((void *)(v), _vec_len(v) * sizeof((v)[0]), (l) * sizeof((v)[0])); \
181  _vec_len(v) = (l); \
182 } while (0)
183 #else /* __COVERITY__ */
184 #define vec_set_len(v, l) do { \
185  _vec_len(v) = (l); \
186 } while (0)
187 #endif /* __COVERITY__ */
188 
189 /** \brief Reset vector length to zero
190  NULL-pointer tolerant
191 */
192 #define vec_reset_length(v) do { if (v) vec_set_len (v, 0); } while (0)
193 
194 /** \brief End (last data address) of vector. */
195 #define vec_end(v) ((v) + vec_len (v))
196 
197 /** \brief True if given pointer is within given vector. */
198 #define vec_is_member(v,e) ((e) >= (v) && (e) < vec_end (v))
199 
200 /** \brief Get vector value at index i checking that i is in bounds. */
201 #define vec_elt_at_index(v,i) \
202 ({ \
203  ASSERT ((i) < vec_len (v)); \
204  (v) + (i); \
205 })
206 
207 /** \brief Get vector value at index i */
208 #define vec_elt(v,i) (vec_elt_at_index(v,i))[0]
209 
210 /** \brief Vector iterator */
211 #define vec_foreach(var,vec) for (var = (vec); var < vec_end (vec); var++)
212 
213 /** \brief Vector iterator (reverse) */
214 #define vec_foreach_backwards(var,vec) \
215 for (var = vec_end (vec) - 1; var >= (vec); var--)
216 
217 /** \brief Iterate over vector indices. */
218 #define vec_foreach_index(var,v) for ((var) = 0; (var) < vec_len (v); (var)++)
219 
220 /** \brief Iterate over vector indices (reverse). */
221 #define vec_foreach_index_backwards(var,v) \
222  for ((var) = vec_len((v)) - 1; (var) >= 0; (var)--)
223 
224 /** \brief return the NUMA index for a vector */
226 vec_get_numa (void *v)
227 {
228  vec_header_t *vh;
229  if (v == 0)
230  return 0;
231  vh = _vec_find (v);
232  return vh->numa_id;
233 }
234 
235 #endif /* included_clib_vec_bootstrap_h */
236 
237 /*
238  * fd.io coding-style-patch-verification: ON
239  *
240  * Local Variables:
241  * eval: (c-set-style "gnu")
242  * End:
243  */
u8 numa_id
NUMA id.
Definition: vec_bootstrap.h:58
unsigned char u8
Definition: types.h:56
static uword vec_header_bytes(uword header_bytes)
Definition: vec_bootstrap.h:79
static uword vec_get_numa(void *v)
return the NUMA index for a vector
unsigned int u32
Definition: types.h:88
static uword vec_aligned_header_bytes(uword header_bytes, uword align)
#define always_inline
Definition: ipsec.h:28
static void * vec_aligned_header(void *v, uword header_bytes, uword align)
static uword round_pow2(uword x, uword pow2)
Definition: clib.h:256
u32 len
Number of elements in vector (NOT its allocated length).
Definition: vec_bootstrap.h:57
vector header structure
Definition: vec_bootstrap.h:55
u64 uword
Definition: types.h:112
static void * vec_aligned_header_end(void *v, uword header_bytes, uword align)
static void * vec_header(void *v, uword header_bytes)
Find a user vector header.
Definition: vec_bootstrap.h:92
static void * vec_header_end(void *v, uword header_bytes)
Find the end of user vector header.