1 VPPINFRA (Infrastructure)
2 =========================
4 The files associated with the VPP Infrastructure layer are located in
5 the ./src/vppinfra folder.
7 VPPinfra is a collection of basic c-library services, quite
8 sufficient to build standalone programs to run directly on bare metal.
9 It also provides high-performance dynamic arrays, hashes, bitmaps,
10 high-precision real-time clock support, fine-grained event-logging, and
11 data structure serialization.
13 One fair comment / fair warning about vppinfra: you can\'t always tell a
14 macro from an inline function from an ordinary function simply by name.
15 Macros are used to avoid function calls in the typical case, and to
16 cause (intentional) side-effects.
18 Vppinfra has been around for almost 20 years and tends not to change
19 frequently. The VPP Infrastructure layer contains the following
25 Vppinfra vectors are ubiquitous dynamically resized arrays with by user
26 defined \"headers\". Many vpppinfra data structures (e.g. hash, heap,
27 pool) are vectors with various different headers.
29 The memory layout looks like this:
32 User header (optional, uword aligned)
33 Alignment padding (if needed)
34 Vector length in elements
35 User's pointer -> Vector element 0
41 As shown above, the vector APIs deal with pointers to the 0th element of
42 a vector. Null pointers are valid vectors of length zero.
44 To avoid thrashing the memory allocator, one often resets the length of
45 a vector to zero while retaining the memory allocation. Set the vector
46 length field to zero via the vec\_reset\_length(v) macro. \[Use the
47 macro! It's smart about NULL pointers.\]
49 Typically, the user header is not present. User headers allow for other
50 data structures to be built atop vppinfra vectors. Users may specify the
51 alignment for data elements via the [vec]()\*\_aligned macros.
53 Vectors elements can be any C type e.g. (int, double, struct bar). This
54 is also true for data types built atop vectors (e.g. heap, pool, etc.).
55 Many macros have \_a variants supporting alignment of vector data and
56 \_h variants supporting non-zero-length vector headers. The \_ha
57 variants support both.
59 Inconsistent usage of header and/or alignment related macro variants
60 will cause delayed, confusing failures.
62 Standard programming error: memorize a pointer to the ith element of a
63 vector, and then expand the vector. Vectors expand by 3/2, so such code
64 may appear to work for a period of time. Correct code almost always
65 memorizes vector **indices** which are invariant across reallocations.
67 In typical application images, one supplies a set of global functions
68 designed to be called from gdb. Here are a few examples:
70 - vl(v) - prints vec\_len(v)
71 - pe(p) - prints pool\_elts(p)
72 - pifi(p, index) - prints pool\_is\_free\_index(p, index)
73 - debug\_hex\_bytes (p, nbytes) - hex memory dump nbytes starting at p
75 Use the "show gdb" debug CLI command to print the current set.
80 Vppinfra bitmaps are dynamic, built using the vppinfra vector APIs.
81 Quite handy for a variety jobs.
86 Vppinfra pools combine vectors and bitmaps to rapidly allocate and free
87 fixed-size data structures with independent lifetimes. Pools are perfect
88 for allocating per-session structures.
93 Vppinfra provides several hash flavors. Data plane problems involving
94 packet classification / session lookup often use
95 ./src/vppinfra/bihash\_template.\[ch\] bounded-index extensible
96 hashes. These templates are instantiated multiple times, to efficiently
97 service different fixed-key sizes.
99 Bihashes are thread-safe. Read-locking is not required. A simple
100 spin-lock ensures that only one thread writes an entry at a time.
102 The original vppinfra hash implementation in
103 ./src/vppinfra/hash.\[ch\] are simple to use, and are often used in
104 control-plane code which needs exact-string-matching.
106 In either case, one almost always looks up a key in a hash table to
107 obtain an index in a related vector or pool. The APIs are simple enough,
108 but one must take care when using the unmanaged arbitrary-sized key
109 variant. Hash\_set\_mem (hash\_table, key\_pointer, value) memorizes
110 key\_pointer. It is usually a bad mistake to pass the address of a
111 vector element as the second argument to hash\_set\_mem. It is perfectly
112 fine to memorize constant string addresses in the text segment.
117 Vppinfra format is roughly equivalent to printf.
119 Format has a few properties worth mentioning. Format's first argument is
120 a (u8 \*) vector to which it appends the result of the current format
121 operation. Chaining calls is very easy:
126 result = format (0, "junk = %d, ", junk);
127 result = format (result, "more junk = %d\n", more_junk);
130 As previously noted, NULL pointers are perfectly proper 0-length
131 vectors. Format returns a (u8 \*) vector, **not** a C-string. If you
132 wish to print a (u8 \*) vector, use the "%v" format string. If you need
133 a (u8 \*) vector which is also a proper C-string, either of these
139 result = format (result, "<whatever>%c", 0);
142 Remember to vec\_free() the result if appropriate. Be careful not to
143 pass format an uninitialized (u8 \*).
145 Format implements a particularly handy user-format scheme via the "%U"
146 format specification. For example:
149 u8 * format_junk (u8 * s, va_list *va)
151 junk = va_arg (va, u32);
152 s = format (s, "%s", junk);
156 result = format (0, "junk = %U, format_junk, "This is some junk");
159 format\_junk() can invoke other user-format functions if desired. The
160 programmer shoulders responsibility for argument type-checking. It is
161 typical for user format functions to blow up if the va\_arg(va,
162 type) macros don't match the caller's idea of reality.
167 Vppinfra unformat is vaguely related to scanf, but considerably more
170 A typical use case involves initializing an unformat\_input\_t from
171 either a C-string or a (u8 \*) vector, then parsing via unformat() as
175 unformat_input_t input;
177 unformat_init_string (&input, "<some-C-string>");
179 unformat_init_vector (&input, <u8-vector>);
182 Then loop parsing individual elements:
185 while (unformat_check_input (&input) != UNFORMAT_END_OF_INPUT)
187 if (unformat (&input, "value1 %d", &value1))
188 ;/* unformat sets value1 */
189 else if (unformat (&input, "value2 %d", &value2)
190 ;/* unformat sets value2 */
192 return clib_error_return (0, "unknown input '%U'",
193 format_unformat_error, input);
197 As with format, unformat implements a user-unformat function capability
198 via a "%U" user unformat function scheme.
200 Vppinfra errors and warnings
201 ----------------------------
203 Many functions within the vpp dataplane have return-values of type
204 clib\_error\_t \*. Clib\_error\_t's are arbitrary strings with a bit of
205 metadata \[fatal, warning\] and are easy to announce. Returning a NULL
206 clib\_error\_t \* indicates "A-OK, no error."
208 Clib\_warning(format-args) is a handy way to add debugging
209 output; clib warnings prepend function:line info to unambiguously locate
210 the message source. Clib\_unix\_warning() adds perror()-style Linux
211 system-call information. In production images, clib\_warnings result in
217 Vppinfra serialization support allows the programmer to easily serialize
218 and unserialize complex data structures.
220 The underlying primitive serialize/unserialize functions use network
221 byte-order, so there are no structural issues serializing on a
222 little-endian host and unserializing on a big-endian host.