FD.io VPP  v20.09-64-g4f7b92f0a
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 u32 vec_len_not_inline (void *v);
144 
145 /** \brief Vector's NUMA id (lvalue-capable)
146 
147  _vec_numa(v) does not check for null, but can be used as an lvalue
148  (e.g. _vec_numa(v) = 1).
149 */
150 
151 #define _vec_numa(v) (_vec_find(v)->numa_id)
152 
153 /** \brief Return vector's NUMA ID (rvalue-only, NULL tolerant)
154  vec_numa(v) checks for NULL, but cannot be used as an lvalue.
155 */
156 #define vec_numa(v) ((v) ? _vec_numa(v) : 0)
157 
158 
159 /** \brief Number of data bytes in vector. */
160 
161 #define vec_bytes(v) (vec_len (v) * sizeof (v[0]))
162 
163 /** \brief Total number of bytes that can fit in vector with current allocation. */
164 
165 #define vec_capacity(v,b) \
166 ({ \
167  void * _vec_capacity_v = (void *) (v); \
168  uword _vec_capacity_b = (b); \
169  _vec_capacity_b = sizeof (vec_header_t) + _vec_round_size (_vec_capacity_b); \
170  _vec_capacity_v ? clib_mem_size (_vec_capacity_v - _vec_capacity_b) : 0; \
171 })
172 
173 /** \brief Total number of elements that can fit into vector. */
174 #define vec_max_len(v) (vec_capacity(v,0) / sizeof (v[0]))
175 
176 /** \brief Set vector length to a user-defined value */
177 #ifndef __COVERITY__ /* Coverity gets confused by ASSERT() */
178 #define vec_set_len(v, l) do { \
179  ASSERT(v); \
180  ASSERT((l) <= vec_max_len(v)); \
181  CLIB_MEM_POISON_LEN((void *)(v), _vec_len(v) * sizeof((v)[0]), (l) * sizeof((v)[0])); \
182  _vec_len(v) = (l); \
183 } while (0)
184 #else /* __COVERITY__ */
185 #define vec_set_len(v, l) do { \
186  _vec_len(v) = (l); \
187 } while (0)
188 #endif /* __COVERITY__ */
189 
190 /** \brief Reset vector length to zero
191  NULL-pointer tolerant
192 */
193 #define vec_reset_length(v) do { if (v) vec_set_len (v, 0); } while (0)
194 
195 /** \brief End (last data address) of vector. */
196 #define vec_end(v) ((v) + vec_len (v))
197 
198 /** \brief True if given pointer is within given vector. */
199 #define vec_is_member(v,e) ((e) >= (v) && (e) < vec_end (v))
200 
201 /** \brief Get vector value at index i checking that i is in bounds. */
202 #define vec_elt_at_index(v,i) \
203 ({ \
204  ASSERT ((i) < vec_len (v)); \
205  (v) + (i); \
206 })
207 
208 /** \brief Get vector value at index i */
209 #define vec_elt(v,i) (vec_elt_at_index(v,i))[0]
210 
211 /** \brief Vector iterator */
212 #define vec_foreach(var,vec) for (var = (vec); var < vec_end (vec); var++)
213 
214 /** \brief Vector iterator (reverse) */
215 #define vec_foreach_backwards(var,vec) \
216 for (var = vec_end (vec) - 1; var >= (vec); var--)
217 
218 /** \brief Iterate over vector indices. */
219 #define vec_foreach_index(var,v) for ((var) = 0; (var) < vec_len (v); (var)++)
220 
221 /** \brief Iterate over vector indices (reverse). */
222 #define vec_foreach_index_backwards(var,v) \
223  for ((var) = vec_len((v)) - 1; (var) >= 0; (var)--)
224 
225 /** \brief return the NUMA index for a vector */
227 vec_get_numa (void *v)
228 {
229  vec_header_t *vh;
230  if (v == 0)
231  return 0;
232  vh = _vec_find (v);
233  return vh->numa_id;
234 }
235 
236 #endif /* included_clib_vec_bootstrap_h */
237 
238 /*
239  * fd.io coding-style-patch-verification: ON
240  *
241  * Local Variables:
242  * eval: (c-set-style "gnu")
243  * End:
244  */
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
u32 vec_len_not_inline(void *v)
Definition: vec.c:144
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:264
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.