1 .\" $OpenBSD: mbuf_tags.9,v 1.18 2003/12/08 07:07:35 mcbride Exp $
3 .\" The authors of this manual page are Angelos D. Keromytis
4 .\" (angelos@cis.upenn.edu), Gleb Smirnoff <glebius@FreeBSD.org>, and
5 .\" Robert Watson <rwatson@FreeBSD.org>
7 .\" Copyright (c) 2004 Robert N. M. Watson
8 .\" Copyright (c) 2001 Angelos D. Keromytis
10 .\" Permission to use, copy, and modify this software with or without
11 .\" fee is hereby granted, provided that this entire notice is included
12 .\" in all source code copies of any software which is or includes a copy
13 .\" or modification of this software.
15 .\" THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR
16 .\" IMPLIED WARRANTY. IN PARTICULAR, NONE OF THE AUTHORS MAKES ANY
17 .\" REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE
18 .\" MERCHANTABILITY OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR
28 .Nd a framework for generic packet attributes
32 .Fn m_tag_alloc "uint32_t cookie" "int type" "int len" "int wait"
34 .Fn m_tag_copy "struct m_tag *t" "int how"
36 .Fn m_tag_copy_chain "struct mbuf *to" "struct mbuf *from" "int how"
38 .Fn m_tag_delete "struct mbuf *m" "struct m_tag *t"
40 .Fn m_tag_delete_chain "struct mbuf *m" "struct m_tag *t"
42 .Fn m_tag_delete_nonpersistent "struct mbuf *m"
44 .Fn m_tag_find "struct mbuf *m" "int type" "struct m_tag *start"
46 .Fn m_tag_first "struct mbuf *m"
48 .Fn m_tag_free "struct m_tag *t"
50 .Fn m_tag_get "int type" "int len" "int wait"
52 .Fn m_tag_init "struct mbuf *m"
54 .Fn m_tag_locate "struct mbuf *m" "uint32_t cookie" "int type" "struct m_tag *t"
56 .Fn m_tag_next "struct mbuf *m" "struct m_tag *t"
58 .Fn m_tag_prepend "struct mbuf *m" "struct m_tag *t"
60 .Fn m_tag_unlink "struct mbuf *m" "struct m_tag *t"
62 Mbuf tags allow additional meta-data to be associated with in-flight packets
63 by providing a mechanism for the tagging of additional kernel memory onto
65 Tags are maintained in chains off of the
67 header, and maintained using a series of API calls to allocate, search, and
69 Tags are identified using an ID and cookie that uniquely identify a class
70 of data tagged onto the packet, and may contain an arbitrary amount of
72 Typical uses of mbuf tags include Mandatory Access Control (MAC) labels as
75 IPsec policy information as described in
77 and packet filter tags used by
80 Tags will be maintained across a variety of operations, including the copying
81 of packet headers using facilities such as
85 Any tags associated with an mbuf header will be automatically freed when the
86 mbuf is freed, although some subsystems will wish to delete the tags prior
89 Packet tags are used by different kernel APIs
90 to keep track of operations done or
91 scheduled to happen to packets.
92 Each packet tag can be distinguished by its type and cookie.
93 The cookie is used to identify a specific module or API.
94 The packet tags are attached to mbuf packet headers.
97 .Fn sizeof "struct m_tag"
98 bytes of a tag contain a
102 SLIST_ENTRY(m_tag) m_tag_link; /* List of packet tags */
103 uint16_t m_tag_id; /* Tag ID */
104 uint16_t m_tag_len; /* Length of data */
105 uint32_t m_tag_cookie; /* ABI/Module ID */
106 void (*m_tag_free)(struct m_tag *);
112 field is used to link tags together (see
116 .Va m_tag_id , m_tag_len
119 fields are set to type, length,
121 cookie, respectively.
124 .Fn m_tag_free_default .
125 Following this structure are
127 bytes of space that can be used to store tag-specific information.
128 Addressing this data region may be tricky.
129 A safe way is embedding
131 into a private data structure, as follows:
132 .Bd -literal -offset indent
137 struct foo *p = (struct foo *)m_tag_alloc(...);
138 struct m_tag *mtag = &p->tag;
143 does not support cookies, it needs
145 to be globally unique.
146 To keep compatibility with
150 is provided along with some compatibility functions.
153 compatible code, one should be careful not to take already
155 Tag types are defined in
157 .Ss Packet Tag Manipulation Functions
158 .Bl -ohang -offset indent
159 .It Fn m_tag_alloc cookie type len wait
160 Allocate a new tag of type
166 bytes of space following the tag header itself.
169 argument is passed directly to
173 returns a memory buffer of
174 .Pq Va len No + Fn sizeof "struct m_tag"
179 A compatibility function
182 .It Fn m_tag_copy tag how
187 argument is passed directly to
189 The return values are the same as in
191 .It Fn m_tag_copy_chain tombuf frommbuf how
192 Allocate and copy all tags from mbuf
196 Returns 1 on success, and 0 on failure.
197 In the latter case, mbuf
199 loses all its tags, even previously present.
200 .It Fn m_tag_delete mbuf tag
206 .It Fn m_tag_delete_chain mbuf tag
207 Remove and free a packet tag chain, starting from
213 all tags are deleted.
214 .It Fn m_tag_delete_nonpersistent mbuf
217 tags and delete those which do not have the
220 .It Fn m_tag_first mbuf
221 Return the first tag associated with
223 .It Fn m_tag_free tag
230 .Fn m_tag_free_default
233 .It Fn m_tag_init mbuf
234 Initialize the tag storage for packet
236 .It Fn m_tag_locate mbuf cookie type tag
237 Search for a tag defined by
243 starting from position specified by
247 then search through the whole list.
248 Upon success, a pointer to the first found tag is returned.
252 A compatibility function
255 .It Fn m_tag_next mbuf tag
263 .It Fn m_tag_prepend mbuf tag
266 at the head of the tag list for packet
268 .It Fn m_tag_unlink mbuf tag
271 from the list of tags of packet
275 The tag-manipulating code is contained in the file
276 .Pa sys/kern/uipc_mbuf2.c .
277 Inlined functions are defined in
283 The packet tags first appeared in
286 .An Angelos D. Keromytis Aq angelos@openbsd.org .