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 */ 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