share/man/man9/mbuf_tags.9

   1 .\"     $OpenBSD: mbuf_tags.9,v 1.18 2003/12/08 07:07:35 mcbride Exp $
   2 .\"
   3 .\" The authors of this manual page are Angelos D. Keromytis
   4 .\" (angelos@cis.upenn.edu), Gleb Smirnoff <glebius@cell.sick.ru>, and
   5 .\" Robert Watson <rwatson@FreeBSD.org>
   6 .\"
   7 .\" Copyright (c) 2004 Robert N. M. Watson
   8 .\" Copyright (c) 2001 Angelos D. Keromytis
   9 .\"
  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.
  14 .\"
  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
  19 .\" PURPOSE.
  20 .\"
  21 .\" $FreeBSD$
  22 .\"
  23 .Dd November 18, 2004
  24 .Dt MBUF_TAGS 9
  25 .Os
  26 .Sh NAME
  27 .Nm mbuf_tags
  28 .Nd a framework for generic packet attributes
  29 .Sh SYNOPSIS
  30 .In sys/mbuf.h
  31 .Ft "struct m_tag *"
  32 .Fn m_tag_alloc "u_int32_t cookie" "int type" "int len" "int wait"
  33 .Ft "struct m_tag *"
  34 .Fn m_tag_copy "struct m_tag *t" "int how"
  35 .Ft int
  36 .Fn m_tag_copy_chain "struct mbuf *to" "struct mbuf *from" "int how"
  37 .Ft void
  38 .Fn m_tag_delete "struct mbuf *m" "struct m_tag *t"
  39 .Ft void
  40 .Fn m_tag_delete_chain "struct mbuf *m" "struct m_tag *t"
  41 .Ft void
  42 .Fn m_tag_delete_nonpersistent "struct mbuf *m"
  43 .Ft "struct m_tag *"
  44 .Fn m_tag_find "struct mbuf *m" "int type" "struct m_tag *start"
  45 .Ft "struct m_tag *"
  46 .Fn m_tag_first "struct mbuf *m"
  47 .Ft void
  48 .Fn m_tag_free "struct m_tag *t"
  49 .Ft "struct m_tag *"
  50 .Fn m_tag_get "int type" "int len" "int wait"
  51 .Ft void
  52 .Fn m_tag_init "struct mbuf *m"
  53 .Ft struct m_tag *
  54 .Fn m_tag_locate "struct mbuf *m" "u_int32_t cookie" "int type" "struct m_tag *t"
  55 .Ft "struct m_tag *"
  56 .Fn m_tag_next "struct mbuf *m" "struct m_tag *t"
  57 .Ft void
  58 .Fn m_tag_prepend "struct mbuf *m" "struct m_tag *t"
  59 .Ft void
  60 .Fn m_tag_unlink "struct mbuf *m" "struct m_tag *t"
  61 .Sh DESCRIPTION
  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
  64 packet header mbufs.
  65 Tags are maintained in chains off of the
  66 .Xr mbuf 9
  67 header, and maintained using a series of API calls to allocate, search, and
  68 delete tags.
  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
  71 additional storage.
  72 Typical uses of mbuf tags include the storage of VLAN tags as described in
  73 .Xr vlan 4 ,
  74 Mandatory Access Control (MAC) labels as described in
  75 .Xr mac 9 ,
  76 IPsec policy information as described in
  77 .Xr ipsec 4 ,
  78 and packet filter tags used by
  79 .Xr pf 4 .
  80 .Pp
  81 Tags will be maintained across a variety of operations, including the copying
  82 of packet headers using facilities such as
  83 .Fn M_COPY_PKTHDR
  84 and
  85 .Fn M_MOVE_PKTHDR .
  86 Any tags associated with an mbuf header will be automatically freed when the
  87 mbuf is freed, although some subsystems will wish to delete the tags prior
  88 to that time.
  89 .Pp
  90 Packet tags are used by different kernel APIs
  91 to keep track of operations done or
  92 scheduled to happen to packets.
  93 Each packet tag can be distinguished by its type and cookie.
  94 The cookie is used to identify a specific module or API.
  95 The packet tags are attached to mbuf packet headers.
  96 .Pp
  97 The first
  98 .Fn sizeof "struct m_tag"
  99 bytes of a tag contain a
 100 .Vt "struct m_tag" :
 101 .Bd -literal
 102 struct m_tag {
 103         SLIST_ENTRY(m_tag)      m_tag_link;     /* List of packet tags */
 104         u_int16_t               m_tag_id;       /* Tag ID */
 105         u_int16_t               m_tag_len;      /* Length of data */
 106         u_int32_t               m_tag_cookie;   /* ABI/Module ID */
 107         void                    (*m_tag_free)(struct m_tag *);
 108 };
 109 .Ed
 110 .Pp
 111 The
 112 .Va m_tag_link
 113 field is used to link tags together (see
 114 .Xr queue 3
 115 for more details).
 116 The
 117 .Va m_tag_id , m_tag_len
 118 and
 119 .Va m_tag_cookie
 120 fields are set to type, length,
 121 and
 122 cookie, respectively.
 123 .Va m_tag_free
 124 points to
 125 .Fn m_tag_free_default .
 126 Following this structure are
 127 .Va m_tag_len
 128 bytes of space that can be used to store tag-specific information.
 129 Addressing this data region may be tricky.
 130 A safe way is embedding
 131 .Vt "struct m_tag"
 132 into a private data structure, as follows:
 133 .Bd -literal -offset indent
 134 struct foo {
 135         struct m_tag    tag;
 136         ...
 137 };
 138 struct foo *p = (struct foo *)m_tag_alloc(...);
 139 struct m_tag *mtag = &p->tag;
 140 .Ed
 141 .Pp
 142 Note that
 143 .Ox
 144 does not support cookies, it needs
 145 .Va m_tag_id
 146 to be globally unique.
 147 To keep compatibility with
 148 .Ox ,
 149 a cookie
 150 .Dv MTAG_ABI_COMPAT
 151 is provided along with some compatibility functions.
 152 When writing an
 153 .Ox
 154 compatible code, one should be careful not to take already
 155 used tag type.
 156 Tag types are defined in
 157 .In sys/mbuf.h .
 158 .Ss Packet Tag Manipulation Functions
 159 .Bl -ohang -offset indent
 160 .It Fn m_tag_alloc cookie type len wait
 161 Allocate a new tag of type
 162 .Fa type
 163 and cookie
 164 .Fa cookie
 165 with
 166 .Va len
 167 bytes of space following the tag header itself.
 168 The
 169 .Fa wait
 170 argument is passed directly to
 171 .Xr malloc 9 .
 172 If successful,
 173 .Fn m_tag_alloc
 174 returns a memory buffer of
 175 .Pq Va len No + Fn sizeof "struct m_tag"
 176 bytes.
 177 Otherwise,
 178 .Dv NULL
 179 is returned.
 180 A compatibility function
 181 .Fn m_tag_get
 182 is also provided.
 183 .It Fn m_tag_copy tag how
 184 Allocate a copy of
 185 .Fa tag .
 186 The
 187 .Fa how
 188 argument is passed directly to
 189 .Fn m_tag_alloc .
 190 The return values are the same as in
 191 .Fn m_tag_alloc .
 192 .It Fn m_tag_copy_chain tombuf frommbuf how
 193 Allocate and copy all tags from mbuf
 194 .Fa frommbuf
 195 to mbuf
 196 .Fa tombuf .
 197 Returns 1 on success, and 0 on failure.
 198 In the latter case, mbuf
 199 .Fa tombuf
 200 loses all its tags, even previously present.
 201 .It Fn m_tag_delete mbuf tag
 202 Remove
 203 .Fa tag
 204 from
 205 .Fa mbuf Ns 's
 206 list and free it.
 207 .It Fn m_tag_delete_chain mbuf tag
 208 Remove and free a packet tag chain, starting from
 209 .Fa tag .
 210 If
 211 .Fa tag
 212 is
 213 .Dv NULL ,
 214 all tags are deleted.
 215 .It Fn m_tag_delete_nonpersistent mbuf
 216 Traverse
 217 .Fa mbuf Ns 's
 218 tags and delete those which do not have the
 219 .Dv MTAG_PERSISTENT
 220 flag set.
 221 .It Fn m_tag_first mbuf
 222 Return the first tag associated with
 223 .Fa mbuf .
 224 .It Fn m_tag_free tag
 225 Free
 226 .Fa tag
 227 using its
 228 .Va m_tag_free
 229 method.
 230 The
 231 .Fn m_tag_free_default
 232 function
 233 is used by default.
 234 .It Fn m_tag_init mbuf
 235 Initialize the tag storage for packet
 236 .Fa mbuf .
 237 .It Fn m_tag_locate mbuf cookie type tag
 238 Search for a tag defined by
 239 .Fa type
 240 and
 241 .Fa cookie
 242 in
 243 .Fa mbuf ,
 244 starting from position specified by
 245 .Fa tag .
 246 If the latter is
 247 .Dv NULL ,
 248 then search through the whole list.
 249 Upon success, a pointer to the first found tag is returned.
 250 In either case,
 251 .Dv NULL
 252 is returned.
 253 A compatibility function
 254 .Fn m_tag_find
 255 is also provided.
 256 .It Fn m_tag_next mbuf tag
 257 Return tag next to
 258 .Fa tag
 259 in
 260 .Fa mbuf .
 261 If absent,
 262 .Dv NULL
 263 is returned.
 264 .It Fn m_tag_prepend mbuf tag
 265 Add the new tag
 266 .Fa tag
 267 at the head of the tag list for packet
 268 .Fa mbuf .
 269 .It Fn m_tag_unlink mbuf tag
 270 Remove tag
 271 .Fa tag
 272 from the list of tags of packet
 273 .Fa mbuf .
 274 .El
 275 .Sh CODE REFERENCES
 276 The tag-manipulating code is contained in the file
 277 .Pa sys/kern/uipc_mbuf2.c .
 278 Inlined functions are defined in
 279 .In sys/mbuf.h .
 280 .Sh SEE ALSO
 281 .Xr queue 3 ,
 282 .Xr mbuf 9
 283 .Sh HISTORY
 284 The packet tags first appeared in
 285 .Ox 2.9
 286 and were written by
 287 .An Angelos D. Keromytis Aq angelos@openbsd.org .