mbuf_tags
- a framework for generic packet attributes
SYNOPSIS
#include <sys/mbuf.h> struct m_tag *
m_tag_alloc (u_int32_t cookie int type int len int wait); struct m_tag *
m_tag_copy (struct m_tag *t int how); int
m_tag_copy_chain (struct mbuf *to struct mbuf *from int how); void
m_tag_delete (struct mbuf *m struct m_tag *t); void
m_tag_delete_chain (struct mbuf *m struct m_tag *t); void
m_tag_delete_nonpersistent (struct mbuf *m); struct m_tag *
m_tag_find (struct mbuf *m int type struct m_tag *start); struct m_tag *
m_tag_first (struct mbuf *m); void
m_tag_free (struct m_tag *t); struct m_tag *
m_tag_get (int type int len int wait); void
m_tag_init (struct mbuf *m); struct m_tag *
m_tag_locate (struct mbuf *m u_int32_t cookie int type struct m_tag *t); struct m_tag *
m_tag_next (struct mbuf *m struct m_tag *t); void
m_tag_prepend (struct mbuf *m struct m_tag *t); void
m_tag_unlink (struct mbuf *m struct m_tag *t);
DESCRIPTION
Mbuf tags allow additional meta-data to be associated with in-flight packets
by providing a mechanism for the tagging of additional kernel memory onto
packet header mbufs.
Tags are maintained in chains off of the
mbuf(9)
header, and maintained using a series of API calls to allocate, search, and
delete tags.
Tags are identified using an ID and cookie that uniquely identify a class
of data tagged onto the packet, and may contain an arbitrary amount of
additional storage.
Typical uses of mbuf tags include Mandatory Access Control (MAC) labels as
described in
mac(9),
IPsec policy information as described in
ipsec(4),
and packet filter tags used by
pf(4).
Tags will be maintained across a variety of operations, including the copying
of packet headers using facilities such as
M_COPY_PKTHDR ();
and
M_MOVE_PKTHDR (.);
Any tags associated with an mbuf header will be automatically freed when the
mbuf is freed, although some subsystems will wish to delete the tags prior
to that time.
Packet tags are used by different kernel APIs
to keep track of operations done or
scheduled to happen to packets.
Each packet tag can be distinguished by its type and cookie.
The cookie is used to identify a specific module or API.
The packet tags are attached to mbuf packet headers.
The first
sizeof (struct m_tag);
bytes of a tag contain a
Vt struct m_tag :
struct m_tag {
SLIST_ENTRY(m_tag) m_tag_link; /* List of packet tags */
u_int16_t m_tag_id; /* Tag ID */
u_int16_t m_tag_len; /* Length of data */
u_int32_t m_tag_cookie; /* ABI/Module ID */
void (*m_tag_free)(struct m_tag *);
};
The
m_tag_link
field is used to link tags together (see
queue(3)
for more details).
The
m_tag_id , m_tag_len
and
m_tag_cookie
fields are set to type, length,
and
cookie, respectively.
m_tag_free
points to
m_tag_free_default (.);
Following this structure are
m_tag_len
bytes of space that can be used to store tag-specific information.
Addressing this data region may be tricky.
A safe way is embedding
Vt struct m_tag
into a private data structure, as follows:
Note that
Ox does not support cookies, it needs
m_tag_id
to be globally unique.
To keep compatibility with
Ox ,
a cookie
MTAG_ABI_COMPAT
is provided along with some compatibility functions.
When writing an
Ox compatible code, one should be careful not to take already
used tag type.
Tag types are defined in
In sys/mbuf.h .
Packet Tag Manipulation Functions
Fn m_tag_alloc cookie type len wait
Allocate a new tag of type
Fa type
and cookie
Fa cookie
with
len
bytes of space following the tag header itself.
The
Fa wait
argument is passed directly to
malloc(9).
If successful,
m_tag_alloc ();
returns a memory buffer of
(len + Fn sizeof struct m_tag
)
bytes.
Otherwise,
NULL
is returned.
A compatibility function
m_tag_get ();
is also provided.
Fn m_tag_copy tag how
Allocate a copy of
Fa tag .
The
Fa how
argument is passed directly to
m_tag_alloc (.);
The return values are the same as in
m_tag_alloc (.);
Fn m_tag_copy_chain tombuf frommbuf how
Allocate and copy all tags from mbuf
Fa frommbuf
to mbuf
Fa tombuf .
Returns 1 on success, and 0 on failure.
In the latter case, mbuf
Fa tombuf
loses all its tags, even previously present.
Fn m_tag_delete mbuf tag
Remove
Fa tag
from
Fa mbuf Ns 's
list and free it.
Fn m_tag_delete_chain mbuf tag
Remove and free a packet tag chain, starting from
Fa tag .
If
Fa tag
is
NULL
all tags are deleted.
Fn m_tag_delete_nonpersistent mbuf
Traverse
Fa mbuf Ns 's
tags and delete those which do not have the
MTAG_PERSISTENT
flag set.
Fn m_tag_first mbuf
Return the first tag associated with
Fa mbuf .
Fn m_tag_free tag
Free
Fa tag
using its
m_tag_free
method.
The
m_tag_free_default ();
function
is used by default.
Fn m_tag_init mbuf
Initialize the tag storage for packet
Fa mbuf .
Fn m_tag_locate mbuf cookie type tag
Search for a tag defined by
Fa type
and
Fa cookie
in
Fa mbuf ,
starting from position specified by
Fa tag .
If the latter is
NULL
then search through the whole list.
Upon success, a pointer to the first found tag is returned.
In either case,
NULL
is returned.
A compatibility function
m_tag_find ();
is also provided.
Fn m_tag_next mbuf tag
Return tag next to
Fa tag
in
Fa mbuf .
If absent,
NULL
is returned.
Fn m_tag_prepend mbuf tag
Add the new tag
Fa tag
at the head of the tag list for packet
Fa mbuf .
Fn m_tag_unlink mbuf tag
Remove tag
Fa tag
from the list of tags of packet
Fa mbuf .
CODE REFERENCES
The tag-manipulating code is contained in the file
sys/kern/uipc_mbuf2.c
Inlined functions are defined in
In sys/mbuf.h .
