1 /*-
2 * SPDX-License-Identifier: BSD-2-Clause
3 *
4 * Copyright (C) 2018 Universita` di Pisa
5 * All rights reserved.
6 *
7 * Redistribution and use in source and binary forms, with or without
8 * modification, are permitted provided that the following conditions
9 * are met:
10 *
11 * 1. Redistributions of source code must retain the above copyright
12 * notice, this list of conditions and the following disclaimer.
13 * 2. Redistributions in binary form must reproduce the above copyright
14 * notice, this list of conditions and the following disclaimer in the
15 * documentation and/or other materials provided with the distribution.
16 *
17 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
18 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20 * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
21 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
22 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
23 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
24 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
25 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
26 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
27 * SUCH DAMAGE.
28 */
29
30 #ifndef LIBNETMAP_H_
31 #define LIBNETMAP_H_
32 /* if thread-safety is not needed, define LIBNETMAP_NOTHREADSAFE before including
33 * this file.
34 */
35
36 /* NOTE: we include net/netmap_user.h without defining NETMAP_WITH_LIBS, which
37 * is deprecated. If you still need it, please define NETMAP_WITH_LIBS and
38 * include net/netmap_user.h before including this file.
39 */
40 #include <net/netmap_user.h>
41
42 struct nmctx;
43 struct nmport_d;
44 struct nmem_d;
45
46 /*
47 * A port open specification (portspec for brevity) has the following syntax
48 * (square brackets delimit optional parts):
49 *
50 * subsystem:vpname[mode][options]
51 *
52 * The "subsystem" is denoted by a prefix, possibly followed by an identifier.
53 * There can be several kinds of subsystems, each one selected by a unique
54 * prefix. Currently defined subsystems are:
55 *
56 * netmap (no id allowed)
57 * the standard subsystem
58 *
59 * vale (followed by a possibly empty id)
60 * the vpname is connected to a VALE switch identified by
61 * the id (an empty id selects the default switch)
62 *
63 * The "vpname" has the following syntax:
64 *
65 * identifier or
66 * identifier1{identifier2 or
67 * identifier1}identifier2
68 *
69 * Identifiers are sequences of alphanumeric characters. The part that begins
70 * with either '{' or '}', when present, denotes a netmap pipe opened in the
71 * same memory region as the subsystem:indentifier1 port.
72 *
73 * The "mode" can be one of the following:
74 *
75 * ^ bind all host (sw) ring pairs
76 * ^NN bind individual host ring pair
77 * * bind host and NIC ring pairs
78 * -NN bind individual NIC ring pair
79 * @NN open the port in the NN memory region
80 * a suffix starting with / and the following flags,
81 * in any order:
82 * x exclusive access
83 * z zero copy monitor (both tx and rx)
84 * t monitor tx side (copy monitor)
85 * r monitor rx side (copy monitor)
86 * R bind only RX ring(s)
87 * T bind only TX ring(s)
88 *
89 * The "options" start at the first '@' character not followed by a number.
90 * Each option starts with '@' and has the following syntax:
91 *
92 * option (flag option)
93 * option=value (single key option)
94 * option:key1=value1,key2=value2,... (multi-key option)
95 *
96 * For multi-key options, the keys can be assigned in any order, but they
97 * cannot be assigned more than once. It is not necessary to assign all the
98 * option keys: unmentioned keys will receive default values. Some multi-key
99 * options define a default key and also accept the single-key syntax, by
100 * assigning the value to this key.
101 *
102 * NOTE: Options may be silently ignored if the port is already open by some
103 * other process.
104 *
105 * The currently available options are (default keys, when defined, are marked
106 * with '*'):
107 *
108 * share (single-key)
109 * open the port in the same memory region used by the
110 * given port name (the port name must be given in
111 * subsystem:vpname form)
112 *
113 * conf (multi-key)
114 * specify the rings/slots numbers (effective only on
115 * ports that are created by the open operation itself,
116 * and ignored otherwise).
117 *
118 * The keys are:
119 *
120 * *rings number of tx and rx rings
121 * tx-rings number of tx rings
122 * rx-rings number of rx rings
123 * host-rings number of tx and rx host rings
124 * host-tx-rings number of host tx rings
125 * host-rx-rings number of host rx rings
126 * slots number of slots in each tx and rx
127 * ring
128 * tx-slots number of slots in each tx ring
129 * rx-slots number of slots in each rx ring
130 *
131 * (more specific keys override the less specific ones)
132 * All keys default to zero if not assigned, and the
133 * corresponding value will be chosen by netmap.
134 *
135 * extmem (multi-key)
136 * open the port in the memory region obtained by
137 * mmap()ing the given file.
138 *
139 * The keys are:
140 *
141 * *file the file to mmap
142 * if-num number of pre-allocated netmap_if's
143 * if-size size of each netmap_if
144 * ring-num number of pre-allocated netmap_ring's
145 * ring-size size of each netmap_ring
146 * buf-num number of pre-allocated buffers
147 * buf-size size of each buffer
148 *
149 * file must be assigned. The other keys default to zero,
150 * causing netmap to take the corresponding values from
151 * the priv_{if,ring,buf}_{num,size} sysctls.
152 *
153 * offset (multi-key)
154 * reserve (part of) the ptr fields as an offset field
155 * and write an initial offset into them.
156 *
157 * The keys are:
158 *
159 * bits number of bits of ptr to use
160 * *initial initial offset value
161 *
162 * initial must be assigned. If bits is omitted, it
163 * defaults to the entire ptr field. The max offset is set
164 * at the same value as the initial offset. Note that the
165 * actual values may be increased by the kernel.
166 *
167 * This option is disabled by default (see
168 * nmport_enable_option() below)
169 */
170
171
172 /* nmport manipulation */
173
174 /* struct nmport_d - describes a netmap port */
175 struct nmport_d {
176 /* see net/netmap.h for the definition of these fields */
177 struct nmreq_header hdr;
178 struct nmreq_register reg;
179
180 /* all the fields below should be considered read-only */
181
182 /* if the same context is used throughout the program, d1->mem ==
183 * d2->mem iff d1 and d2 are using the memory region (i.e., zero
184 * copy is possible between the two ports)
185 */
186 struct nmem_d *mem;
187
188 /* the nmctx used when this nmport_d was created */
189 struct nmctx *ctx;
190
191 int register_done; /* nmport_register() has been called */
192 int mmap_done; /* nmport_mmap() has been called */
193 /* pointer to the extmem option contained in the hdr options, if any */
194 struct nmreq_opt_extmem *extmem;
195
196 /* the fields below are compatible with nm_open() */
197 int fd; /* "/dev/netmap", -1 if not open */
198 struct netmap_if *nifp; /* pointer to the netmap_if */
199 uint16_t first_tx_ring;
200 uint16_t last_tx_ring;
201 uint16_t first_rx_ring;
202 uint16_t last_rx_ring;
203 uint16_t cur_tx_ring; /* used by nmport_inject */
204 uint16_t cur_rx_ring;
205
206 /* LIFO list of cleanup functions (used internally) */
207 struct nmport_cleanup_d *clist;
208 };
209
210 /* nmport_open - opens a port from a portspec
211 * @portspec the port opening specification
212 *
213 * If successful, the function returns a new nmport_d describing a netmap
214 * port, opened according to the port specification, ready to be used for rx
215 * and/or tx.
216 *
217 * The rings available for tx are in the [first_tx_ring, last_tx_ring]
218 * interval, and similarly for rx. One or both intervals may be empty.
219 *
220 * When done using it, the nmport_d descriptor must be closed using
221 * nmport_close().
222 *
223 * In case of error, NULL is returned, errno is set to some error, and an
224 * error message is sent through the error() method of the current context.
225 */
226 struct nmport_d * nmport_open(const char *portspec);
227
228 /* nport_close - close a netmap port
229 * @d the port we want to close
230 *
231 * Undoes the actions performed by the nmport_open that created d, then
232 * frees the descriptor.
233 */
234 void nmport_close(struct nmport_d *d);
235
236 /* nmport_inject - sends a packet
237 * @d the port through which we want to send
238 * @buf base address of the packet
239 * @size its size in bytes
240 *
241 * Sends a packet using the cur_tx_ring and updates the index
242 * to use all available tx rings in turn. Note: the packet is copied.
243 *
244 * Returns 0 on success an -1 on error.
245 */
246 int nmport_inject(struct nmport_d *d, const void *buf, size_t size);
247
248 /*
249 * the functions below can be used to split the functionality of
250 * nmport_open when special features (e.g., extra buffers) are needed
251 *
252 * The relation among the functions is as follows:
253 *
254 * |nmport_new
255 * |nmport_prepare = |
256 * | |nmport_parse
257 * nmport_open =|
258 * | |nmport_register
259 * |nmport_open_desc =|
260 * |nmport_mmap
261 *
262 */
263
264 /* nmport_new - create a new nmport_d
265 *
266 * Creates a new nmport_d using the malloc() method of the current default
267 * context. Returns NULL on error, setting errno to an error value.
268 */
269 struct nmport_d *nmport_new(void);
270
271 /* nmport_parse - fills the nmport_d netmap-register request
272 * @d the nmport to be filled
273 * @portspec the port opening specification
274 *
275 * This function parses the portspec and initizalizes the @d->hdr and @d->reg
276 * fields. It may need to allocate a list of options. If an extmem option is
277 * found, it may also mmap() the corresponding file.
278 *
279 * It returns 0 on success. On failure it returns -1, sets errno to an error
280 * value and sends an error message to the error() method of the context used
281 * when @d was created. Moreover, *@d is left unchanged.
282 */
283 int nmport_parse(struct nmport_d *d, const char *portspec);
284
285 /* nmport_register - registers the port with netmap
286 * @d the nmport to be registered
287 *
288 * This function obtains a netmap file descriptor and registers the port with
289 * netmap. The @d->hdr and @d->reg data structures must have been previously
290 * initialized (via nmport_parse() or otherwise).
291 *
292 * It returns 0 on success. On failure it returns -1, sets errno to an error
293 * value and sends an error message to the error() method of the context used
294 * when @d was created. Moreover, *@d is left unchanged.
295 */
296 int nmport_register(struct nmport_d *);
297
298 /* nmport_mmap - maps the port resources into the process memory
299 * @d the nmport to be mapped
300 *
301 * The port must have been previously been registered using nmport_register.
302 *
303 * Note that if extmem is used (either via an option or by calling an
304 * nmport_extmem_* function before nmport_register()), no new mmap() is issued.
305 *
306 * It returns 0 on success. On failure it returns -1, sets errno to an error
307 * value and sends an error message to the error() method of the context used
308 * when @d was created. Moreover, *@d is left unchanged.
309 */
310 int nmport_mmap(struct nmport_d *);
311
312 /* the following functions undo the actions of nmport_new(), nmport_parse(),
313 * nmport_register() and nmport_mmap(), respectively.
314 */
315 void nmport_delete(struct nmport_d *);
316 void nmport_undo_parse(struct nmport_d *);
317 void nmport_undo_register(struct nmport_d *);
318 void nmport_undo_mmap(struct nmport_d *);
319
320 /* nmport_prepare - create a port descriptor, but do not open it
321 * @portspec the port opening specification
322 *
323 * This functions creates a new nmport_d and initializes it according to
324 * @portspec. It is equivalent to nmport_new() followed by nmport_parse().
325 *
326 * It returns 0 on success. On failure it returns -1, sets errno to an error
327 * value and sends an error message to the error() method of the context used
328 * when @d was created. Moreover, *@d is left unchanged.
329 */
330 struct nmport_d *nmport_prepare(const char *portspec);
331
332 /* nmport_open_desc - open an initialized port descriptor
333 * @d the descriptor we want to open
334 *
335 * Registers the port with netmap and maps the rings and buffers into the
336 * process memory. It is equivalent to nmport_register() followed by
337 * nmport_mmap().
338 *
339 * It returns 0 on success. On failure it returns -1, sets errno to an error
340 * value and sends an error message to the error() method of the context used
341 * when @d was created. Moreover, *@d is left unchanged.
342 */
343 int nmport_open_desc(struct nmport_d *d);
344
345 /* the following functions undo the actions of nmport_prepare()
346 * and nmport_open_desc(), respectively.
347 */
348 void nmport_undo_prepare(struct nmport_d *);
349 void nmport_undo_open_desc(struct nmport_d *);
350
351 /* nmport_clone - copy an nmport_d
352 * @d the nmport_d we want to copy
353 *
354 * Copying an nmport_d by hand should be avoided, since adjustments are needed
355 * and some part of the state cannot be easily duplicated. This function
356 * creates a copy of @d in a safe way. The returned nmport_d contains
357 * nmreq_header and nmreq_register structures equivalent to those contained in
358 * @d, except for the option list, which is ignored. The returned nmport_d is
359 * already nmport_prepare()d, but it must still be nmport_open_desc()ed. The
360 * new nmport_d uses the same nmctx as @d.
361 *
362 * If extmem was used for @d, then @d cannot be nmport_clone()d until it has
363 * been nmport_register()ed.
364 *
365 * In case of error, the function returns NULL, sets errno to an error value
366 * and sends an error message to the nmctx error() method.
367 */
368 struct nmport_d *nmport_clone(struct nmport_d *);
369
370 /* nmport_extmem - use extmem for this port
371 * @d the port we want to use the extmem for
372 * @base the base address of the extmem region
373 * @size the size in bytes of the extmem region
374 *
375 * the memory that contains the netmap ifs, rings and buffers is usually
376 * allocated by netmap and later mmap()ed by the applications. It is sometimes
377 * useful to reverse this process, by having the applications allocate some
378 * memory (through mmap() or otherwise) and then let netmap use it. The extmem
379 * option can be used to implement this latter strategy. The option can be
380 * passed through the portspec using the '@extmem:...' syntax, or
381 * programmatically by calling nmport_extmem() or nmport_extmem_from_file()
382 * between nmport_parse() and nmport_register() (or between nmport_prepare()
383 * and nmport_open_desc()).
384 *
385 * It returns 0 on success. On failure it returns -1, sets errno to an error
386 * value and sends an error message to the error() method of the context used
387 * when @d was created. Moreover, *@d is left unchanged.
388 */
389 int nmport_extmem(struct nmport_d *d, void *base, size_t size);
390
391 /* nmport_extmem_from_file - use the extmem obtained by mapping a file
392 * @d the port we want to use the extmem for
393 * @fname path of the file we want to map
394 *
395 * This works like nmport_extmem, but the extmem memory is obtained by
396 * mmap()ping @fname. nmport_close() will also automatically munmap() the file.
397 *
398 * It returns 0 on success. On failure it returns -1, sets errno to an error
399 * value and sends an error message to the error() method of the context used
400 * when @d was created. Moreover, *@d is left unchanged.
401 */
402 int nmport_extmem_from_file(struct nmport_d *d, const char *fname);
403
404 /* nmport_extmem_getinfo - opbtai a pointer to the extmem configuration
405 * @d the port we want to obtain the pointer from
406 *
407 * Returns a pointer to the nmreq_pools_info structure containing the
408 * configuration of the extmem attached to port @d, or NULL if no extmem
409 * is attached. This can be used to set the desired configuration before
410 * registering the port, or to read the actual configuration after
411 * registration.
412 */
413 struct nmreq_pools_info* nmport_extmem_getinfo(struct nmport_d *d);
414
415
416 /* nmport_offset - use offsets for this port
417 * @initial the initial offset for all the slots
418 * @maxoff the maximum offset
419 * @bits the number of bits of slot->ptr to use for the offsets
420 * @mingap the minimum gap between offsets (in shared buffers)
421 *
422 * With this option the lower @bits bits of the ptr field in the netmap_slot
423 * can be used to specify an offset into the buffer. All offsets will be set
424 * to the @initial value by netmap.
425 *
426 * The offset field can be read and updated using the bitmask found in
427 * ring->offset_mask after a successful register. netmap_user.h contains
428 * some helper macros (NETMAP_ROFFSET, NETMAP_WOFFSET and NETMAP_BUF_OFFSET).
429 *
430 * For RX rings, the user writes the offset o in an empty slot before passing
431 * it to netmap; then, netmap will write the incoming packet at an offset o' >=
432 * o in the buffer. o' may be larger than o because of, e.g., alignment
433 * constrains. If o' > o netmap will also update the offset field in the slot.
434 * Note that large offsets may cause the port to split the packet over several
435 * slots, setting the NS_MOREFRAG flag accordingly.
436 *
437 * For TX rings, the user may prepare the packet to send at an offset o into
438 * the buffer and write o in the offset field. Netmap will send the packets
439 * starting o bytes in the buffer. Note that the address of the packet must
440 * comply with any alignment constraints that the port may have, or the result
441 * will be undefined. The user may read the alignment constraint in the new
442 * ring->buf_align field. It is also possible that empty slots already come
443 * with a non-zero offset o specified in the offset field. In this case, the
444 * user will have to write the packet at an offset o' >= o.
445 *
446 * The user must also declare the @maxoff offset that she is going to use. Any
447 * offset larger than this will be truncated.
448 *
449 * The user may also declare a @mingap (ignored if zero) if she plans to use
450 * offsets to share the same buffer among several slots. Netmap will guarantee
451 * that it will never write more than @mingap bytes for each slot, irrespective
452 * of the buffer length.
453 */
454 int nmport_offset(struct nmport_d *d, uint64_t initial, uint64_t maxoff,
455 uint64_t bits, uint64_t mingap);
456
457 /* enable/disable options
458 *
459 * These functions can be used to disable options that the application cannot
460 * or doesn't want to handle, or to enable options that require special support
461 * from the application and are, therefore, disabled by default. Disabled
462 * options will cause an error if encountered during option parsing.
463 *
464 * If the option is unknown, nmport_disable_option is a NOP, while
465 * nmport_enable_option returns -1 and sets errno to EOPNOTSUPP.
466 *
467 * These functions are not threadsafe and are meant to be used at the beginning
468 * of the program.
469 */
470 void nmport_disable_option(const char *opt);
471 int nmport_enable_option(const char *opt);
472
473 /* nmreq manipulation
474 *
475 * nmreq_header_init - initialize an nmreq_header
476 * @hdr the nmreq_header to initialize
477 * @reqtype the kind of netmap request
478 * @body the body of the request
479 *
480 * Initialize the nr_version, nr_reqtype and nr_body fields of *@hdr.
481 * The other fields are set to zero.
482 */
483 void nmreq_header_init(struct nmreq_header *hdr, uint16_t reqtype, void *body);
484
485 /*
486 * These functions allow for finer grained parsing of portspecs. They are used
487 * internally by nmport_parse().
488 */
489
490 /* nmreq_header_decode - initialize an nmreq_header
491 * @ppspec: (in/out) pointer to a pointer to the portspec
492 * @hdr: pointer to the nmreq_header to be initialized
493 * @ctx: pointer to the nmctx to use (for errors)
494 *
495 * This function fills the @hdr the nr_name field with the port name extracted
496 * from *@pifname. The other fields of *@hdr are unchanged. The @pifname is
497 * updated to point at the first char past the port name.
498 *
499 * Returns 0 on success. In case of error, -1 is returned with errno set to
500 * EINVAL, @pifname is unchanged, *@hdr is also unchanged, and an error message
501 * is sent through @ctx->error().
502 */
503 int nmreq_header_decode(const char **ppspec, struct nmreq_header *hdr,
504 struct nmctx *ctx);
505
506 /* nmreq_regiter_decode - initialize an nmreq_register
507 * @pmode: (in/out) pointer to a pointer to an opening mode
508 * @reg: pointer to the nmreq_register to be initialized
509 * @ctx: pointer to the nmctx to use (for errors)
510 *
511 * This function fills the nr_mode, nr_ringid, nr_flags and nr_mem_id fields of
512 * the structure pointed by @reg, according to the opening mode specified by
513 * *@pmode. The other fields of *@reg are unchanged. The @pmode is updated to
514 * point at the first char past the opening mode.
515 *
516 * If a '@' is encountered followed by something which is not a number, parsing
517 * stops (without error) and @pmode is left pointing at the '@' char. The
518 * nr_mode, nr_ringid and nr_flags fields are still updated, but nr_mem_id is
519 * not touched and the interpretation of the '@' field is left to the caller.
520 *
521 * Returns 0 on success. In case of error, -1 is returned with errno set to
522 * EINVAL, @pmode is unchanged, *@reg is also unchanged, and an error message
523 * is sent through @ctx->error().
524 */
525 int nmreq_register_decode(const char **pmode, struct nmreq_register *reg,
526 struct nmctx *ctx);
527
528 /* nmreq_options_decode - parse the "options" part of the portspec
529 * @opt: pointer to the option list
530 * @parsers: list of option parsers
531 * @token: token to pass to each parser
532 * @ctx: pointer to the nmctx to use (for errors and malloc/free)
533 *
534 * This function parses each option in @opt. Each option is matched (based on
535 * the "option" prefix) to a corresponding parser in @parsers. The function
536 * checks that the syntax is appropriate for the parser and it assigns all the
537 * keys mentioned in the option. It then passes control to the parser, to
538 * interpret the keys values.
539 *
540 * Returns 0 on success. In case of error, -1 is returned, errno is set to an
541 * error value and a message is sent to @ctx->error(). The effects of partially
542 * interpreted options may not be undone.
543 */
544 struct nmreq_opt_parser;
545 int nmreq_options_decode(const char *opt, struct nmreq_opt_parser *parsers,
546 void *token, struct nmctx *ctx);
547
548 struct nmreq_parse_ctx;
549 /* type of the option-parsers callbacks */
550 typedef int (*nmreq_opt_parser_cb)(struct nmreq_parse_ctx *);
551
552 #define NMREQ_OPT_MAXKEYS 16 /* max nr of recognized keys per option */
553
554 /* struct nmreq_opt_key - describes an option key */
555 struct nmreq_opt_key {
556 const char *key; /* the key name */
557 int id; /* its position in the parse context */
558 unsigned int flags;
559 #define NMREQ_OPTK_ALLOWEMPTY (1U << 0) /* =value may be omitted */
560 #define NMREQ_OPTK_MUSTSET (1U << 1) /* the key is mandatory */
561 #define NMREQ_OPTK_DEFAULT (1U << 2) /* this is the default key */
562 };
563
564 /* struct nmreq_opt_parser - describes an option parser */
565 struct nmreq_opt_parser {
566 const char *prefix; /* matches one option prefix */
567 nmreq_opt_parser_cb parse; /* the parse callback */
568 int default_key; /* which option is the default if the
569 parser is multi-key (-1 if none) */
570 int nr_keys;
571 unsigned int flags;
572 #define NMREQ_OPTF_DISABLED (1U << 0)
573 #define NMREQ_OPTF_ALLOWEMPTY (1U << 1) /* =value can be omitted */
574
575 struct nmreq_opt_parser *next; /* list of options */
576
577 /* recognized keys */
578 struct nmreq_opt_key keys[NMREQ_OPT_MAXKEYS];
579 } __attribute__((aligned(16)));
580
581 /* struct nmreq_parse_ctx - the parse context received by the parse callback */
582 struct nmreq_parse_ctx {
583 struct nmctx *ctx; /* the nmctx for errors and malloc/free */
584 void *token; /* the token passed to nmreq_options_parse */
585
586 /* the value (i.e., the part after the = sign) of each recognized key
587 * is assigned to the corresponding entry in this array, based on the
588 * key id. Unassigned keys are left at NULL.
589 */
590 const char *keys[NMREQ_OPT_MAXKEYS];
591 };
592
593 /* nmreq_get_mem_id - get the mem_id of the given port
594 * @portname pointer to a pointer to the portname
595 * @ctx pointer to the nmctx to use (for errors)
596 *
597 * *@portname must point to a substem:vpname porname, possibly followed by
598 * something else.
599 *
600 * If successful, returns the mem_id of *@portname and moves @portname past the
601 * subsystem:vpname part of the input. In case of error it returns -1, sets
602 * errno to an error value and sends an error message to ctx->error().
603 */
604 int32_t nmreq_get_mem_id(const char **portname, struct nmctx *ctx);
605
606 /* option list manipulation */
607 void nmreq_push_option(struct nmreq_header *, struct nmreq_option *);
608 void nmreq_remove_option(struct nmreq_header *, struct nmreq_option *);
609 struct nmreq_option *nmreq_find_option(struct nmreq_header *, uint32_t);
610 void nmreq_free_options(struct nmreq_header *);
611 const char* nmreq_option_name(uint32_t);
612 #define nmreq_foreach_option(h_, o_) \
613 for ((o_) = (struct nmreq_option *)((uintptr_t)((h_)->nr_options));\
614 (o_) != NULL;\
615 (o_) = (struct nmreq_option *)((uintptr_t)((o_)->nro_next)))
616
617 /* nmctx manipulation */
618
619 /* the nmctx serves a few purposes:
620 *
621 * - maintain a list of all memory regions open by the program, so that two
622 * ports that are using the same region (as identified by the mem_id) will
623 * point to the same nmem_d instance.
624 *
625 * - allow the user to specify how to lock accesses to the above list, if
626 * needed (lock() callback)
627 *
628 * - allow the user to specify how error messages should be delivered (error()
629 * callback)
630 *
631 * - select the verbosity of the library (verbose field); if verbose==0, no
632 * errors are sent to the error() callback
633 *
634 * - allow the user to override the malloc/free functions used by the library
635 * (malloc() and free() callbacks)
636 *
637 */
638 typedef void (*nmctx_error_cb)(struct nmctx *, const char *);
639 typedef void *(*nmctx_malloc_cb)(struct nmctx *,size_t);
640 typedef void (*nmctx_free_cb)(struct nmctx *,void *);
641 typedef void (*nmctx_lock_cb)(struct nmctx *, int);
642
643 struct nmctx {
644 int verbose;
645 nmctx_error_cb error;
646 nmctx_malloc_cb malloc;
647 nmctx_free_cb free;
648 nmctx_lock_cb lock;
649
650 struct nmem_d *mem_descs;
651 };
652
653 /* nmctx_get - obtain a pointer to the current default context */
654 struct nmctx *nmctx_get(void);
655
656 /* nmctx_set_default - change the default context
657 * @ctx pointer to the new context
658 *
659 * Returns a pointer to the previous default context.
660 */
661 struct nmctx *nmctx_set_default(struct nmctx *ctx);
662
663 /* internal functions and data structures */
664
665 /* struct nmem_d - describes a memory region currently used */
666 struct nmem_d {
667 uint16_t mem_id; /* the region netmap identifier */
668 int refcount; /* how many nmport_d's point here */
669 void *mem; /* memory region base address */
670 size_t size; /* memory region size */
671 int is_extmem; /* was it obtained via extmem? */
672
673 /* pointers for the circular list implementation.
674 * The list head is the mem_descs filed in the nmctx
675 */
676 struct nmem_d *next;
677 struct nmem_d *prev;
678 };
679
680 /* a trick to force the inclusion of libpthread only if requested. If
681 * LIBNETMAP_NOTHREADSAFE is defined, no pthread symbol is imported.
682 *
683 * There is no need to actually call this function: the ((used)) attribute is
684 * sufficient to include it in the image.
685 */
libnetmap_init(void)686 static __attribute__((used)) void libnetmap_init(void)
687 {
688 #ifndef LIBNETMAP_NOTHREADSAFE
689 extern int nmctx_threadsafe;
690 /* dummy assignment to link-in the nmctx-pthread.o object. The proper
691 * inizialization is performed only once in the library constructor
692 * defined there.
693 */
694 nmctx_threadsafe = 1;
695 #endif /* LIBNETMAP_NOTHREADSAFE */
696 }
697
698 /* nmctx_set_threadsafe - install a threadsafe default context
699 *
700 * called by the constructor in nmctx-pthread.o to initialize a lock and install
701 * the lock() callback in the default context.
702 */
703 void nmctx_set_threadsafe(void);
704
705 /* nmctx_ferror - format and send an error message */
706 void nmctx_ferror(struct nmctx *, const char *, ...);
707 /* nmctx_malloc - allocate memory */
708 void *nmctx_malloc(struct nmctx *, size_t);
709 /* nmctx_free - free memory allocated via nmctx_malloc */
710 void nmctx_free(struct nmctx *, void *);
711 /* nmctx_lock - lock the list of nmem_d */
712 void nmctx_lock(struct nmctx *);
713 /* nmctx_unlock - unlock the list of nmem_d */
714 void nmctx_unlock(struct nmctx *);
715
716 #endif /* LIBNETMAP_H_ */
717