717 lines
27 KiB
C
717 lines
27 KiB
C
/*-
|
|
* SPDX-License-Identifier: BSD-2-Clause
|
|
*
|
|
* Copyright (C) 2018 Universita` di Pisa
|
|
* All rights reserved.
|
|
*
|
|
* Redistribution and use in source and binary forms, with or without
|
|
* modification, are permitted provided that the following conditions
|
|
* are met:
|
|
*
|
|
* 1. Redistributions of source code must retain the above copyright
|
|
* notice, this list of conditions and the following disclaimer.
|
|
* 2. Redistributions in binary form must reproduce the above copyright
|
|
* notice, this list of conditions and the following disclaimer in the
|
|
* documentation and/or other materials provided with the distribution.
|
|
*
|
|
* THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
|
* ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
* ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
|
* FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
* OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
* LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
* OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
* SUCH DAMAGE.
|
|
*/
|
|
|
|
#ifndef LIBNETMAP_H_
|
|
#define LIBNETMAP_H_
|
|
/* if thread-safety is not needed, define LIBNETMAP_NOTHREADSAFE before including
|
|
* this file.
|
|
*/
|
|
|
|
/* NOTE: we include net/netmap_user.h without defining NETMAP_WITH_LIBS, which
|
|
* is deprecated. If you still need it, please define NETMAP_WITH_LIBS and
|
|
* include net/netmap_user.h before including this file.
|
|
*/
|
|
#include <net/netmap_user.h>
|
|
|
|
struct nmctx;
|
|
struct nmport_d;
|
|
struct nmem_d;
|
|
|
|
/*
|
|
* A port open specification (portspec for brevity) has the following syntax
|
|
* (square brackets delimit optional parts):
|
|
*
|
|
* subsystem:vpname[mode][options]
|
|
*
|
|
* The "subsystem" is denoted by a prefix, possibly followed by an identifier.
|
|
* There can be several kinds of subsystems, each one selected by a unique
|
|
* prefix. Currently defined subsystems are:
|
|
*
|
|
* netmap (no id allowed)
|
|
* the standard subsystem
|
|
*
|
|
* vale (followed by a possibly empty id)
|
|
* the vpname is connected to a VALE switch identified by
|
|
* the id (an empty id selects the default switch)
|
|
*
|
|
* The "vpname" has the following syntax:
|
|
*
|
|
* identifier or
|
|
* identifier1{identifier2 or
|
|
* identifier1}identifier2
|
|
*
|
|
* Identifiers are sequences of alphanumeric characters. The part that begins
|
|
* with either '{' or '}', when present, denotes a netmap pipe opened in the
|
|
* same memory region as the subsystem:indentifier1 port.
|
|
*
|
|
* The "mode" can be one of the following:
|
|
*
|
|
* ^ bind all host (sw) ring pairs
|
|
* ^NN bind individual host ring pair
|
|
* * bind host and NIC ring pairs
|
|
* -NN bind individual NIC ring pair
|
|
* @NN open the port in the NN memory region
|
|
* a suffix starting with / and the following flags,
|
|
* in any order:
|
|
* x exclusive access
|
|
* z zero copy monitor (both tx and rx)
|
|
* t monitor tx side (copy monitor)
|
|
* r monitor rx side (copy monitor)
|
|
* R bind only RX ring(s)
|
|
* T bind only TX ring(s)
|
|
*
|
|
* The "options" start at the first '@' character not followed by a number.
|
|
* Each option starts with '@' and has the following syntax:
|
|
*
|
|
* option (flag option)
|
|
* option=value (single key option)
|
|
* option:key1=value1,key2=value2,... (multi-key option)
|
|
*
|
|
* For multi-key options, the keys can be assigned in any order, but they
|
|
* cannot be assigned more than once. It is not necessary to assign all the
|
|
* option keys: unmentioned keys will receive default values. Some multi-key
|
|
* options define a default key and also accept the single-key syntax, by
|
|
* assigning the value to this key.
|
|
*
|
|
* NOTE: Options may be silently ignored if the port is already open by some
|
|
* other process.
|
|
*
|
|
* The currently available options are (default keys, when defined, are marked
|
|
* with '*'):
|
|
*
|
|
* share (single-key)
|
|
* open the port in the same memory region used by the
|
|
* given port name (the port name must be given in
|
|
* subsystem:vpname form)
|
|
*
|
|
* conf (multi-key)
|
|
* specify the rings/slots numbers (effective only on
|
|
* ports that are created by the open operation itself,
|
|
* and ignored otherwise).
|
|
*
|
|
* The keys are:
|
|
*
|
|
* *rings number of tx and rx rings
|
|
* tx-rings number of tx rings
|
|
* rx-rings number of rx rings
|
|
* host-rings number of tx and rx host rings
|
|
* host-tx-rings number of host tx rings
|
|
* host-rx-rings number of host rx rings
|
|
* slots number of slots in each tx and rx
|
|
* ring
|
|
* tx-slots number of slots in each tx ring
|
|
* rx-slots number of slots in each rx ring
|
|
*
|
|
* (more specific keys override the less specific ones)
|
|
* All keys default to zero if not assigned, and the
|
|
* corresponding value will be chosen by netmap.
|
|
*
|
|
* extmem (multi-key)
|
|
* open the port in the memory region obtained by
|
|
* mmap()ing the given file.
|
|
*
|
|
* The keys are:
|
|
*
|
|
* *file the file to mmap
|
|
* if-num number of pre-allocated netmap_if's
|
|
* if-size size of each netmap_if
|
|
* ring-num number of pre-allocated netmap_ring's
|
|
* ring-size size of each netmap_ring
|
|
* buf-num number of pre-allocated buffers
|
|
* buf-size size of each buffer
|
|
*
|
|
* file must be assigned. The other keys default to zero,
|
|
* causing netmap to take the corresponding values from
|
|
* the priv_{if,ring,buf}_{num,size} sysctls.
|
|
*
|
|
* offset (multi-key)
|
|
* reserve (part of) the ptr fields as an offset field
|
|
* and write an initial offset into them.
|
|
*
|
|
* The keys are:
|
|
*
|
|
* bits number of bits of ptr to use
|
|
* *initial initial offset value
|
|
*
|
|
* initial must be assigned. If bits is omitted, it
|
|
* defaults to the entire ptr field. The max offset is set
|
|
* at the same value as the initial offset. Note that the
|
|
* actual values may be increased by the kernel.
|
|
*
|
|
* This option is disabled by default (see
|
|
* nmport_enable_option() below)
|
|
*/
|
|
|
|
|
|
/* nmport manipulation */
|
|
|
|
/* struct nmport_d - describes a netmap port */
|
|
struct nmport_d {
|
|
/* see net/netmap.h for the definition of these fields */
|
|
struct nmreq_header hdr;
|
|
struct nmreq_register reg;
|
|
|
|
/* all the fields below should be considered read-only */
|
|
|
|
/* if the same context is used throughout the program, d1->mem ==
|
|
* d2->mem iff d1 and d2 are using the memory region (i.e., zero
|
|
* copy is possible between the two ports)
|
|
*/
|
|
struct nmem_d *mem;
|
|
|
|
/* the nmctx used when this nmport_d was created */
|
|
struct nmctx *ctx;
|
|
|
|
int register_done; /* nmport_register() has been called */
|
|
int mmap_done; /* nmport_mmap() has been called */
|
|
/* pointer to the extmem option contained in the hdr options, if any */
|
|
struct nmreq_opt_extmem *extmem;
|
|
|
|
/* the fields below are compatible with nm_open() */
|
|
int fd; /* "/dev/netmap", -1 if not open */
|
|
struct netmap_if *nifp; /* pointer to the netmap_if */
|
|
uint16_t first_tx_ring;
|
|
uint16_t last_tx_ring;
|
|
uint16_t first_rx_ring;
|
|
uint16_t last_rx_ring;
|
|
uint16_t cur_tx_ring; /* used by nmport_inject */
|
|
uint16_t cur_rx_ring;
|
|
|
|
/* LIFO list of cleanup functions (used internally) */
|
|
struct nmport_cleanup_d *clist;
|
|
};
|
|
|
|
/* nmport_open - opens a port from a portspec
|
|
* @portspec the port opening specification
|
|
*
|
|
* If successful, the function returns a new nmport_d describing a netmap
|
|
* port, opened according to the port specification, ready to be used for rx
|
|
* and/or tx.
|
|
*
|
|
* The rings available for tx are in the [first_tx_ring, last_tx_ring]
|
|
* interval, and similarly for rx. One or both intervals may be empty.
|
|
*
|
|
* When done using it, the nmport_d descriptor must be closed using
|
|
* nmport_close().
|
|
*
|
|
* In case of error, NULL is returned, errno is set to some error, and an
|
|
* error message is sent through the error() method of the current context.
|
|
*/
|
|
struct nmport_d * nmport_open(const char *portspec);
|
|
|
|
/* nport_close - close a netmap port
|
|
* @d the port we want to close
|
|
*
|
|
* Undoes the actions performed by the nmport_open that created d, then
|
|
* frees the descriptor.
|
|
*/
|
|
void nmport_close(struct nmport_d *d);
|
|
|
|
/* nmport_inject - sends a packet
|
|
* @d the port through which we want to send
|
|
* @buf base address of the packet
|
|
* @size its size in bytes
|
|
*
|
|
* Sends a packet using the cur_tx_ring and updates the index
|
|
* to use all available tx rings in turn. Note: the packet is copied.
|
|
*
|
|
* Returns 0 on success an -1 on error.
|
|
*/
|
|
int nmport_inject(struct nmport_d *d, const void *buf, size_t size);
|
|
|
|
/*
|
|
* the functions below can be used to split the functionality of
|
|
* nmport_open when special features (e.g., extra buffers) are needed
|
|
*
|
|
* The relation among the functions is as follows:
|
|
*
|
|
* |nmport_new
|
|
* |nmport_prepare = |
|
|
* | |nmport_parse
|
|
* nmport_open =|
|
|
* | |nmport_register
|
|
* |nmport_open_desc =|
|
|
* |nmport_mmap
|
|
*
|
|
*/
|
|
|
|
/* nmport_new - create a new nmport_d
|
|
*
|
|
* Creates a new nmport_d using the malloc() method of the current default
|
|
* context. Returns NULL on error, setting errno to an error value.
|
|
*/
|
|
struct nmport_d *nmport_new(void);
|
|
|
|
/* nmport_parse - fills the nmport_d netmap-register request
|
|
* @d the nmport to be filled
|
|
* @portspec the port opening specification
|
|
*
|
|
* This function parses the portspec and initizalizes the @d->hdr and @d->reg
|
|
* fields. It may need to allocate a list of options. If an extmem option is
|
|
* found, it may also mmap() the corresponding file.
|
|
*
|
|
* It returns 0 on success. On failure it returns -1, sets errno to an error
|
|
* value and sends an error message to the error() method of the context used
|
|
* when @d was created. Moreover, *@d is left unchanged.
|
|
*/
|
|
int nmport_parse(struct nmport_d *d, const char *portspec);
|
|
|
|
/* nmport_register - registers the port with netmap
|
|
* @d the nmport to be registered
|
|
*
|
|
* This function obtains a netmap file descriptor and registers the port with
|
|
* netmap. The @d->hdr and @d->reg data structures must have been previously
|
|
* initialized (via nmport_parse() or otherwise).
|
|
*
|
|
* It returns 0 on success. On failure it returns -1, sets errno to an error
|
|
* value and sends an error message to the error() method of the context used
|
|
* when @d was created. Moreover, *@d is left unchanged.
|
|
*/
|
|
int nmport_register(struct nmport_d *);
|
|
|
|
/* nmport_mmap - maps the port resources into the process memory
|
|
* @d the nmport to be mapped
|
|
*
|
|
* The port must have been previously been registered using nmport_register.
|
|
*
|
|
* Note that if extmem is used (either via an option or by calling an
|
|
* nmport_extmem_* function before nmport_register()), no new mmap() is issued.
|
|
*
|
|
* It returns 0 on success. On failure it returns -1, sets errno to an error
|
|
* value and sends an error message to the error() method of the context used
|
|
* when @d was created. Moreover, *@d is left unchanged.
|
|
*/
|
|
int nmport_mmap(struct nmport_d *);
|
|
|
|
/* the following functions undo the actions of nmport_new(), nmport_parse(),
|
|
* nmport_register() and nmport_mmap(), respectively.
|
|
*/
|
|
void nmport_delete(struct nmport_d *);
|
|
void nmport_undo_parse(struct nmport_d *);
|
|
void nmport_undo_register(struct nmport_d *);
|
|
void nmport_undo_mmap(struct nmport_d *);
|
|
|
|
/* nmport_prepare - create a port descriptor, but do not open it
|
|
* @portspec the port opening specification
|
|
*
|
|
* This functions creates a new nmport_d and initializes it according to
|
|
* @portspec. It is equivalent to nmport_new() followed by nmport_parse().
|
|
*
|
|
* It returns 0 on success. On failure it returns -1, sets errno to an error
|
|
* value and sends an error message to the error() method of the context used
|
|
* when @d was created. Moreover, *@d is left unchanged.
|
|
*/
|
|
struct nmport_d *nmport_prepare(const char *portspec);
|
|
|
|
/* nmport_open_desc - open an initialized port descriptor
|
|
* @d the descriptor we want to open
|
|
*
|
|
* Registers the port with netmap and maps the rings and buffers into the
|
|
* process memory. It is equivalent to nmport_register() followed by
|
|
* nmport_mmap().
|
|
*
|
|
* It returns 0 on success. On failure it returns -1, sets errno to an error
|
|
* value and sends an error message to the error() method of the context used
|
|
* when @d was created. Moreover, *@d is left unchanged.
|
|
*/
|
|
int nmport_open_desc(struct nmport_d *d);
|
|
|
|
/* the following functions undo the actions of nmport_prepare()
|
|
* and nmport_open_desc(), respectively.
|
|
*/
|
|
void nmport_undo_prepare(struct nmport_d *);
|
|
void nmport_undo_open_desc(struct nmport_d *);
|
|
|
|
/* nmport_clone - copy an nmport_d
|
|
* @d the nmport_d we want to copy
|
|
*
|
|
* Copying an nmport_d by hand should be avoided, since adjustments are needed
|
|
* and some part of the state cannot be easily duplicated. This function
|
|
* creates a copy of @d in a safe way. The returned nmport_d contains
|
|
* nmreq_header and nmreq_register structures equivalent to those contained in
|
|
* @d, except for the option list, which is ignored. The returned nmport_d is
|
|
* already nmport_prepare()d, but it must still be nmport_open_desc()ed. The
|
|
* new nmport_d uses the same nmctx as @d.
|
|
*
|
|
* If extmem was used for @d, then @d cannot be nmport_clone()d until it has
|
|
* been nmport_register()ed.
|
|
*
|
|
* In case of error, the function returns NULL, sets errno to an error value
|
|
* and sends an error message to the nmctx error() method.
|
|
*/
|
|
struct nmport_d *nmport_clone(struct nmport_d *);
|
|
|
|
/* nmport_extmem - use extmem for this port
|
|
* @d the port we want to use the extmem for
|
|
* @base the base address of the extmem region
|
|
* @size the size in bytes of the extmem region
|
|
*
|
|
* the memory that contains the netmap ifs, rings and buffers is usually
|
|
* allocated by netmap and later mmap()ed by the applications. It is sometimes
|
|
* useful to reverse this process, by having the applications allocate some
|
|
* memory (through mmap() or otherwise) and then let netmap use it. The extmem
|
|
* option can be used to implement this latter strategy. The option can be
|
|
* passed through the portspec using the '@extmem:...' syntax, or
|
|
* programmatically by calling nmport_extmem() or nmport_extmem_from_file()
|
|
* between nmport_parse() and nmport_register() (or between nmport_prepare()
|
|
* and nmport_open_desc()).
|
|
*
|
|
* It returns 0 on success. On failure it returns -1, sets errno to an error
|
|
* value and sends an error message to the error() method of the context used
|
|
* when @d was created. Moreover, *@d is left unchanged.
|
|
*/
|
|
int nmport_extmem(struct nmport_d *d, void *base, size_t size);
|
|
|
|
/* nmport_extmem_from_file - use the extmem obtained by mapping a file
|
|
* @d the port we want to use the extmem for
|
|
* @fname path of the file we want to map
|
|
*
|
|
* This works like nmport_extmem, but the extmem memory is obtained by
|
|
* mmap()ping @fname. nmport_close() will also automatically munmap() the file.
|
|
*
|
|
* It returns 0 on success. On failure it returns -1, sets errno to an error
|
|
* value and sends an error message to the error() method of the context used
|
|
* when @d was created. Moreover, *@d is left unchanged.
|
|
*/
|
|
int nmport_extmem_from_file(struct nmport_d *d, const char *fname);
|
|
|
|
/* nmport_extmem_getinfo - opbtai a pointer to the extmem configuration
|
|
* @d the port we want to obtain the pointer from
|
|
*
|
|
* Returns a pointer to the nmreq_pools_info structure containing the
|
|
* configuration of the extmem attached to port @d, or NULL if no extmem
|
|
* is attached. This can be used to set the desired configuration before
|
|
* registering the port, or to read the actual configuration after
|
|
* registration.
|
|
*/
|
|
struct nmreq_pools_info* nmport_extmem_getinfo(struct nmport_d *d);
|
|
|
|
|
|
/* nmport_offset - use offsets for this port
|
|
* @initial the initial offset for all the slots
|
|
* @maxoff the maximum offset
|
|
* @bits the number of bits of slot->ptr to use for the offsets
|
|
* @mingap the minimum gap between offsets (in shared buffers)
|
|
*
|
|
* With this option the lower @bits bits of the ptr field in the netmap_slot
|
|
* can be used to specify an offset into the buffer. All offsets will be set
|
|
* to the @initial value by netmap.
|
|
*
|
|
* The offset field can be read and updated using the bitmask found in
|
|
* ring->offset_mask after a successful register. netmap_user.h contains
|
|
* some helper macros (NETMAP_ROFFSET, NETMAP_WOFFSET and NETMAP_BUF_OFFSET).
|
|
*
|
|
* For RX rings, the user writes the offset o in an empty slot before passing
|
|
* it to netmap; then, netmap will write the incoming packet at an offset o' >=
|
|
* o in the buffer. o' may be larger than o because of, e.g., alignment
|
|
* constrains. If o' > o netmap will also update the offset field in the slot.
|
|
* Note that large offsets may cause the port to split the packet over several
|
|
* slots, setting the NS_MOREFRAG flag accordingly.
|
|
*
|
|
* For TX rings, the user may prepare the packet to send at an offset o into
|
|
* the buffer and write o in the offset field. Netmap will send the packets
|
|
* starting o bytes in the buffer. Note that the address of the packet must
|
|
* comply with any alignment constraints that the port may have, or the result
|
|
* will be undefined. The user may read the alignment constraint in the new
|
|
* ring->buf_align field. It is also possible that empty slots already come
|
|
* with a non-zero offset o specified in the offset field. In this case, the
|
|
* user will have to write the packet at an offset o' >= o.
|
|
*
|
|
* The user must also declare the @maxoff offset that she is going to use. Any
|
|
* offset larger than this will be truncated.
|
|
*
|
|
* The user may also declare a @mingap (ignored if zero) if she plans to use
|
|
* offsets to share the same buffer among several slots. Netmap will guarantee
|
|
* that it will never write more than @mingap bytes for each slot, irrespective
|
|
* of the buffer length.
|
|
*/
|
|
int nmport_offset(struct nmport_d *d, uint64_t initial, uint64_t maxoff,
|
|
uint64_t bits, uint64_t mingap);
|
|
|
|
/* enable/disable options
|
|
*
|
|
* These functions can be used to disable options that the application cannot
|
|
* or doesn't want to handle, or to enable options that require special support
|
|
* from the application and are, therefore, disabled by default. Disabled
|
|
* options will cause an error if encountered during option parsing.
|
|
*
|
|
* If the option is unknown, nmport_disable_option is a NOP, while
|
|
* nmport_enable_option returns -1 and sets errno to EOPNOTSUPP.
|
|
*
|
|
* These functions are not threadsafe and are meant to be used at the beginning
|
|
* of the program.
|
|
*/
|
|
void nmport_disable_option(const char *opt);
|
|
int nmport_enable_option(const char *opt);
|
|
|
|
/* nmreq manipulation
|
|
*
|
|
* nmreq_header_init - initialize an nmreq_header
|
|
* @hdr the nmreq_header to initialize
|
|
* @reqtype the kind of netmap request
|
|
* @body the body of the request
|
|
*
|
|
* Initialize the nr_version, nr_reqtype and nr_body fields of *@hdr.
|
|
* The other fields are set to zero.
|
|
*/
|
|
void nmreq_header_init(struct nmreq_header *hdr, uint16_t reqtype, void *body);
|
|
|
|
/*
|
|
* These functions allow for finer grained parsing of portspecs. They are used
|
|
* internally by nmport_parse().
|
|
*/
|
|
|
|
/* nmreq_header_decode - initialize an nmreq_header
|
|
* @ppspec: (in/out) pointer to a pointer to the portspec
|
|
* @hdr: pointer to the nmreq_header to be initialized
|
|
* @ctx: pointer to the nmctx to use (for errors)
|
|
*
|
|
* This function fills the @hdr the nr_name field with the port name extracted
|
|
* from *@pifname. The other fields of *@hdr are unchanged. The @pifname is
|
|
* updated to point at the first char past the port name.
|
|
*
|
|
* Returns 0 on success. In case of error, -1 is returned with errno set to
|
|
* EINVAL, @pifname is unchanged, *@hdr is also unchanged, and an error message
|
|
* is sent through @ctx->error().
|
|
*/
|
|
int nmreq_header_decode(const char **ppspec, struct nmreq_header *hdr,
|
|
struct nmctx *ctx);
|
|
|
|
/* nmreq_regiter_decode - initialize an nmreq_register
|
|
* @pmode: (in/out) pointer to a pointer to an opening mode
|
|
* @reg: pointer to the nmreq_register to be initialized
|
|
* @ctx: pointer to the nmctx to use (for errors)
|
|
*
|
|
* This function fills the nr_mode, nr_ringid, nr_flags and nr_mem_id fields of
|
|
* the structure pointed by @reg, according to the opening mode specified by
|
|
* *@pmode. The other fields of *@reg are unchanged. The @pmode is updated to
|
|
* point at the first char past the opening mode.
|
|
*
|
|
* If a '@' is encountered followed by something which is not a number, parsing
|
|
* stops (without error) and @pmode is left pointing at the '@' char. The
|
|
* nr_mode, nr_ringid and nr_flags fields are still updated, but nr_mem_id is
|
|
* not touched and the interpretation of the '@' field is left to the caller.
|
|
*
|
|
* Returns 0 on success. In case of error, -1 is returned with errno set to
|
|
* EINVAL, @pmode is unchanged, *@reg is also unchanged, and an error message
|
|
* is sent through @ctx->error().
|
|
*/
|
|
int nmreq_register_decode(const char **pmode, struct nmreq_register *reg,
|
|
struct nmctx *ctx);
|
|
|
|
/* nmreq_options_decode - parse the "options" part of the portspec
|
|
* @opt: pointer to the option list
|
|
* @parsers: list of option parsers
|
|
* @token: token to pass to each parser
|
|
* @ctx: pointer to the nmctx to use (for errors and malloc/free)
|
|
*
|
|
* This function parses each option in @opt. Each option is matched (based on
|
|
* the "option" prefix) to a corresponding parser in @parsers. The function
|
|
* checks that the syntax is appropriate for the parser and it assigns all the
|
|
* keys mentioned in the option. It then passes control to the parser, to
|
|
* interpret the keys values.
|
|
*
|
|
* Returns 0 on success. In case of error, -1 is returned, errno is set to an
|
|
* error value and a message is sent to @ctx->error(). The effects of partially
|
|
* interpreted options may not be undone.
|
|
*/
|
|
struct nmreq_opt_parser;
|
|
int nmreq_options_decode(const char *opt, struct nmreq_opt_parser *parsers,
|
|
void *token, struct nmctx *ctx);
|
|
|
|
struct nmreq_parse_ctx;
|
|
/* type of the option-parsers callbacks */
|
|
typedef int (*nmreq_opt_parser_cb)(struct nmreq_parse_ctx *);
|
|
|
|
#define NMREQ_OPT_MAXKEYS 16 /* max nr of recognized keys per option */
|
|
|
|
/* struct nmreq_opt_key - describes an option key */
|
|
struct nmreq_opt_key {
|
|
const char *key; /* the key name */
|
|
int id; /* its position in the parse context */
|
|
unsigned int flags;
|
|
#define NMREQ_OPTK_ALLOWEMPTY (1U << 0) /* =value may be omitted */
|
|
#define NMREQ_OPTK_MUSTSET (1U << 1) /* the key is mandatory */
|
|
#define NMREQ_OPTK_DEFAULT (1U << 2) /* this is the default key */
|
|
};
|
|
|
|
/* struct nmreq_opt_parser - describes an option parser */
|
|
struct nmreq_opt_parser {
|
|
const char *prefix; /* matches one option prefix */
|
|
nmreq_opt_parser_cb parse; /* the parse callback */
|
|
int default_key; /* which option is the default if the
|
|
parser is multi-key (-1 if none) */
|
|
int nr_keys;
|
|
unsigned int flags;
|
|
#define NMREQ_OPTF_DISABLED (1U << 0)
|
|
#define NMREQ_OPTF_ALLOWEMPTY (1U << 1) /* =value can be omitted */
|
|
|
|
struct nmreq_opt_parser *next; /* list of options */
|
|
|
|
/* recognized keys */
|
|
struct nmreq_opt_key keys[NMREQ_OPT_MAXKEYS];
|
|
} __attribute__((aligned(16)));
|
|
|
|
/* struct nmreq_parse_ctx - the parse context received by the parse callback */
|
|
struct nmreq_parse_ctx {
|
|
struct nmctx *ctx; /* the nmctx for errors and malloc/free */
|
|
void *token; /* the token passed to nmreq_options_parse */
|
|
|
|
/* the value (i.e., the part after the = sign) of each recognized key
|
|
* is assigned to the corresponding entry in this array, based on the
|
|
* key id. Unassigned keys are left at NULL.
|
|
*/
|
|
const char *keys[NMREQ_OPT_MAXKEYS];
|
|
};
|
|
|
|
/* nmreq_get_mem_id - get the mem_id of the given port
|
|
* @portname pointer to a pointer to the portname
|
|
* @ctx pointer to the nmctx to use (for errors)
|
|
*
|
|
* *@portname must point to a substem:vpname porname, possibly followed by
|
|
* something else.
|
|
*
|
|
* If successful, returns the mem_id of *@portname and moves @portname past the
|
|
* subsystem:vpname part of the input. In case of error it returns -1, sets
|
|
* errno to an error value and sends an error message to ctx->error().
|
|
*/
|
|
int32_t nmreq_get_mem_id(const char **portname, struct nmctx *ctx);
|
|
|
|
/* option list manipulation */
|
|
void nmreq_push_option(struct nmreq_header *, struct nmreq_option *);
|
|
void nmreq_remove_option(struct nmreq_header *, struct nmreq_option *);
|
|
struct nmreq_option *nmreq_find_option(struct nmreq_header *, uint32_t);
|
|
void nmreq_free_options(struct nmreq_header *);
|
|
const char* nmreq_option_name(uint32_t);
|
|
#define nmreq_foreach_option(h_, o_) \
|
|
for ((o_) = (struct nmreq_option *)((uintptr_t)((h_)->nr_options));\
|
|
(o_) != NULL;\
|
|
(o_) = (struct nmreq_option *)((uintptr_t)((o_)->nro_next)))
|
|
|
|
/* nmctx manipulation */
|
|
|
|
/* the nmctx serves a few purposes:
|
|
*
|
|
* - maintain a list of all memory regions open by the program, so that two
|
|
* ports that are using the same region (as identified by the mem_id) will
|
|
* point to the same nmem_d instance.
|
|
*
|
|
* - allow the user to specify how to lock accesses to the above list, if
|
|
* needed (lock() callback)
|
|
*
|
|
* - allow the user to specify how error messages should be delivered (error()
|
|
* callback)
|
|
*
|
|
* - select the verbosity of the library (verbose field); if verbose==0, no
|
|
* errors are sent to the error() callback
|
|
*
|
|
* - allow the user to override the malloc/free functions used by the library
|
|
* (malloc() and free() callbacks)
|
|
*
|
|
*/
|
|
typedef void (*nmctx_error_cb)(struct nmctx *, const char *);
|
|
typedef void *(*nmctx_malloc_cb)(struct nmctx *,size_t);
|
|
typedef void (*nmctx_free_cb)(struct nmctx *,void *);
|
|
typedef void (*nmctx_lock_cb)(struct nmctx *, int);
|
|
|
|
struct nmctx {
|
|
int verbose;
|
|
nmctx_error_cb error;
|
|
nmctx_malloc_cb malloc;
|
|
nmctx_free_cb free;
|
|
nmctx_lock_cb lock;
|
|
|
|
struct nmem_d *mem_descs;
|
|
};
|
|
|
|
/* nmctx_get - obtain a pointer to the current default context */
|
|
struct nmctx *nmctx_get(void);
|
|
|
|
/* nmctx_set_default - change the default context
|
|
* @ctx pointer to the new context
|
|
*
|
|
* Returns a pointer to the previous default context.
|
|
*/
|
|
struct nmctx *nmctx_set_default(struct nmctx *ctx);
|
|
|
|
/* internal functions and data structures */
|
|
|
|
/* struct nmem_d - describes a memory region currently used */
|
|
struct nmem_d {
|
|
uint16_t mem_id; /* the region netmap identifier */
|
|
int refcount; /* how many nmport_d's point here */
|
|
void *mem; /* memory region base address */
|
|
size_t size; /* memory region size */
|
|
int is_extmem; /* was it obtained via extmem? */
|
|
|
|
/* pointers for the circular list implementation.
|
|
* The list head is the mem_descs filed in the nmctx
|
|
*/
|
|
struct nmem_d *next;
|
|
struct nmem_d *prev;
|
|
};
|
|
|
|
/* a trick to force the inclusion of libpthread only if requested. If
|
|
* LIBNETMAP_NOTHREADSAFE is defined, no pthread symbol is imported.
|
|
*
|
|
* There is no need to actually call this function: the ((used)) attribute is
|
|
* sufficient to include it in the image.
|
|
*/
|
|
static __attribute__((used)) void libnetmap_init(void)
|
|
{
|
|
#ifndef LIBNETMAP_NOTHREADSAFE
|
|
extern int nmctx_threadsafe;
|
|
/* dummy assignment to link-in the nmctx-pthread.o object. The proper
|
|
* inizialization is performed only once in the library constructor
|
|
* defined there.
|
|
*/
|
|
nmctx_threadsafe = 1;
|
|
#endif /* LIBNETMAP_NOTHREADSAFE */
|
|
}
|
|
|
|
/* nmctx_set_threadsafe - install a threadsafe default context
|
|
*
|
|
* called by the constructor in nmctx-pthread.o to initialize a lock and install
|
|
* the lock() callback in the default context.
|
|
*/
|
|
void nmctx_set_threadsafe(void);
|
|
|
|
/* nmctx_ferror - format and send an error message */
|
|
void nmctx_ferror(struct nmctx *, const char *, ...);
|
|
/* nmctx_malloc - allocate memory */
|
|
void *nmctx_malloc(struct nmctx *, size_t);
|
|
/* nmctx_free - free memory allocated via nmctx_malloc */
|
|
void nmctx_free(struct nmctx *, void *);
|
|
/* nmctx_lock - lock the list of nmem_d */
|
|
void nmctx_lock(struct nmctx *);
|
|
/* nmctx_unlock - unlock the list of nmem_d */
|
|
void nmctx_unlock(struct nmctx *);
|
|
|
|
#endif /* LIBNETMAP_H_ */
|