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