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@FreeBSD.org>, 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 January 12, 2008
  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 "uint32_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" "uint32_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 Mandatory Access Control (MAC) labels as
  73 described in
  74 .Xr mac 9 ,
  75 IPsec policy information as described in
  76 .Xr ipsec 4 ,
  77 and packet filter tags used by
  78 .Xr pf 4 .
  79 .Pp
  80 Tags will be maintained across a variety of operations, including the copying
  81 of packet headers using facilities such as
  82 .Fn M_COPY_PKTHDR
  83 and
  84 .Fn M_MOVE_PKTHDR .
  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
  87 to that time.
  88 .Pp
  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.
  95 .Pp
  96 The first
  97 .Fn sizeof "struct m_tag"
  98 bytes of a tag contain a
  99 .Vt "struct m_tag" :
 100 .Bd -literal
 101 struct m_tag {
 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 *);
 107 };
 108 .Ed
 109 .Pp
 110 The
 111 .Va m_tag_link
 112 field is used to link tags together (see
 113 .Xr queue 3
 114 for more details).
 115 The
 116 .Va m_tag_id , m_tag_len
 117 and
 118 .Va m_tag_cookie
 119 fields are set to type, length,
 120 and
 121 cookie, respectively.
 122 .Va m_tag_free
 123 points to
 124 .Fn m_tag_free_default .
 125 Following this structure are
 126 .Va m_tag_len
 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
 130 .Vt "struct m_tag"
 131 into a private data structure, as follows:
 132 .Bd -literal -offset indent
 133 struct foo {
 134         struct m_tag    tag;
 135         ...
 136 };
 137 struct foo *p = (struct foo *)m_tag_alloc(...);
 138 struct m_tag *mtag = &p->tag;
 139 .Ed
 140 .Pp
 141 Note that
 142 .Ox
 143 does not support cookies, it needs
 144 .Va m_tag_id
 145 to be globally unique.
 146 To keep compatibility with
 147 .Ox ,
 148 a cookie
 149 .Dv MTAG_ABI_COMPAT
 150 is provided along with some compatibility functions.
 151 When writing an
 152 .Ox
 153 compatible code, one should be careful not to take already
 154 used tag type.
 155 Tag types are defined in
 156 .In sys/mbuf.h .
 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
 161 .Fa type
 162 and cookie
 163 .Fa cookie
 164 with
 165 .Va len
 166 bytes of space following the tag header itself.
 167 The
 168 .Fa wait
 169 argument is passed directly to
 170 .Xr malloc 9 .
 171 If successful,
 172 .Fn m_tag_alloc
 173 returns a memory buffer of
 174 .Pq Va len No + Fn sizeof "struct m_tag"
 175 bytes.
 176 Otherwise,
 177 .Dv NULL
 178 is returned.
 179 A compatibility function
 180 .Fn m_tag_get
 181 is also provided.
 182 .It Fn m_tag_copy tag how
 183 Allocate a copy of
 184 .Fa tag .
 185 The
 186 .Fa how
 187 argument is passed directly to
 188 .Fn m_tag_alloc .
 189 The return values are the same as in
 190 .Fn m_tag_alloc .
 191 .It Fn m_tag_copy_chain tombuf frommbuf how
 192 Allocate and copy all tags from mbuf
 193 .Fa frommbuf
 194 to mbuf
 195 .Fa tombuf .
 196 Returns 1 on success, and 0 on failure.
 197 In the latter case, mbuf
 198 .Fa tombuf
 199 loses all its tags, even previously present.
 200 .It Fn m_tag_delete mbuf tag
 201 Remove
 202 .Fa tag
 203 from
 204 .Fa mbuf Ns 's
 205 list and free it.
 206 .It Fn m_tag_delete_chain mbuf tag
 207 Remove and free a packet tag chain, starting from
 208 .Fa tag .
 209 If
 210 .Fa tag
 211 is
 212 .Dv NULL ,
 213 all tags are deleted.
 214 .It Fn m_tag_delete_nonpersistent mbuf
 215 Traverse
 216 .Fa mbuf Ns 's
 217 tags and delete those which do not have the
 218 .Dv MTAG_PERSISTENT
 219 flag set.
 220 .It Fn m_tag_first mbuf
 221 Return the first tag associated with
 222 .Fa mbuf .
 223 .It Fn m_tag_free tag
 224 Free
 225 .Fa tag
 226 using its
 227 .Va m_tag_free
 228 method.
 229 The
 230 .Fn m_tag_free_default
 231 function
 232 is used by default.
 233 .It Fn m_tag_init mbuf
 234 Initialize the tag storage for packet
 235 .Fa mbuf .
 236 .It Fn m_tag_locate mbuf cookie type tag
 237 Search for a tag defined by
 238 .Fa type
 239 and
 240 .Fa cookie
 241 in
 242 .Fa mbuf ,
 243 starting from position specified by
 244 .Fa tag .
 245 If the latter is
 246 .Dv NULL ,
 247 then search through the whole list.
 248 Upon success, a pointer to the first found tag is returned.
 249 In either case,
 250 .Dv NULL
 251 is returned.
 252 A compatibility function
 253 .Fn m_tag_find
 254 is also provided.
 255 .It Fn m_tag_next mbuf tag
 256 Return tag next to
 257 .Fa tag
 258 in
 259 .Fa mbuf .
 260 If absent,
 261 .Dv NULL
 262 is returned.
 263 .It Fn m_tag_prepend mbuf tag
 264 Add the new tag
 265 .Fa tag
 266 at the head of the tag list for packet
 267 .Fa mbuf .
 268 .It Fn m_tag_unlink mbuf tag
 269 Remove tag
 270 .Fa tag
 271 from the list of tags of packet
 272 .Fa mbuf .
 273 .El
 274 .Sh CODE REFERENCES
 275 The tag-manipulating code is contained in the file
 276 .Pa sys/kern/uipc_mbuf2.c .
 277 Inlined functions are defined in
 278 .In sys/mbuf.h .
 279 .Sh SEE ALSO
 280 .Xr queue 3 ,
 281 .Xr mbuf 9
 282 .Sh HISTORY
 283 The packet tags first appeared in
 284 .Ox 2.9
 285 and were written by
 286 .An Angelos D. Keromytis Aq angelos@openbsd.org .