FD.io VPP  v21.10.1-2-g0a485f517
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) \
175  ((v) ? (vec_capacity (v,0) - vec_header_bytes (0)) / sizeof (v[0]) : 0)
176 
177 /** \brief Set vector length to a user-defined value */
178 #ifndef __COVERITY__ /* Coverity gets confused by ASSERT() */
179 #define vec_set_len(v, l) do { \
180  ASSERT(v); \
181  ASSERT((l) <= vec_max_len(v)); \
182  CLIB_MEM_POISON_LEN((void *)(v), _vec_len(v) * sizeof((v)[0]), (l) * sizeof((v)[0])); \
183  _vec_len(v) = (l); \
184 } while (0)
185 #else /* __COVERITY__ */
186 #define vec_set_len(v, l) do { \
187  _vec_len(v) = (l); \
188 } while (0)
189 #endif /* __COVERITY__ */
190 
191 /** \brief Reset vector length to zero
192  NULL-pointer tolerant
193 */
194 #define vec_reset_length(v) do { if (v) vec_set_len (v, 0); } while (0)
195 
196 /** \brief End (last data address) of vector. */
197 #define vec_end(v) ((v) + vec_len (v))
198 
199 /** \brief True if given pointer is within given vector. */
200 #define vec_is_member(v,e) ((e) >= (v) && (e) < vec_end (v))
201 
202 /** \brief Get vector value at index i checking that i is in bounds. */
203 #define vec_elt_at_index(v,i) \
204 ({ \
205  ASSERT ((i) < vec_len (v)); \
206  (v) + (i); \
207 })
208 
209 /** \brief Get vector value at index i */
210 #define vec_elt(v,i) (vec_elt_at_index(v,i))[0]
211 
212 /** \brief Vector iterator */
213 #define vec_foreach(var,vec) for (var = (vec); var < vec_end (vec); var++)
214 
215 /** \brief Vector iterator (reverse) */
216 #define vec_foreach_backwards(var,vec) \
217 for (var = vec_end (vec) - 1; var >= (vec); var--)
218 
219 /** \brief Iterate over vector indices. */
220 #define vec_foreach_index(var,v) for ((var) = 0; (var) < vec_len (v); (var)++)
221 
222 /** \brief Iterate over vector indices (reverse). */
223 #define vec_foreach_index_backwards(var,v) \
224  for ((var) = vec_len((v)) - 1; (var) >= 0; (var)--)
225 
226 /** \brief return the NUMA index for a vector */
228 vec_get_numa (void *v)
229 {
230  vec_header_t *vh;
231  if (v == 0)
232  return 0;
233  vh = _vec_find (v);
234  return vh->numa_id;
235 }
236 
237 #endif /* included_clib_vec_bootstrap_h */
238 
239 /*
240  * fd.io coding-style-patch-verification: ON
241  *
242  * Local Variables:
243  * eval: (c-set-style "gnu")
244  * End:
245  */
vec_aligned_header
static void * vec_aligned_header(void *v, uword header_bytes, uword align)
Definition: vec_bootstrap.h:116
vec_aligned_header_bytes
static uword vec_aligned_header_bytes(uword header_bytes, uword align)
Definition: vec_bootstrap.h:110
round_pow2
static uword round_pow2(uword x, uword pow2)
Definition: clib.h:279
vec_header_end
static void * vec_header_end(void *v, uword header_bytes)
Find the end of user vector header.
Definition: vec_bootstrap.h:104
uword
u64 uword
Definition: types.h:112
vec_header
static void * vec_header(void *v, uword header_bytes)
Find a user vector header.
Definition: vec_bootstrap.h:92
vec_len_not_inline
u32 vec_len_not_inline(void *v)
Definition: vec.c:148
vec_get_numa
static uword vec_get_numa(void *v)
return the NUMA index for a vector
Definition: vec_bootstrap.h:228
always_inline
#define always_inline
Definition: rdma_mlx5dv.h:23
u32
unsigned int u32
Definition: types.h:88
vec_header_t::numa_id
u8 numa_id
NUMA id.
Definition: vec_bootstrap.h:58
vec_header_t
vector header structure
Definition: vec_bootstrap.h:55
u8
unsigned char u8
Definition: types.h:56
vec_aligned_header_end
static void * vec_aligned_header_end(void *v, uword header_bytes, uword align)
Definition: vec_bootstrap.h:122
vec_header_bytes
static uword vec_header_bytes(uword header_bytes)
Definition: vec_bootstrap.h:79
vec_header_t::len
u32 len
Number of elements in vector (NOT its allocated length).
Definition: vec_bootstrap.h:57